diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000000..d7c23d6351 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +custom: https://fund.django-rest-framework.org/topics/funding/ diff --git a/.isort.cfg b/.isort.cfg deleted file mode 100644 index 4d4a6a509d..0000000000 --- a/.isort.cfg +++ /dev/null @@ -1,7 +0,0 @@ -[settings] -skip=.tox -atomic=true -multi_line_output=5 -known_standard_library=types -known_third_party=pytest,django -known_first_party=rest_framework diff --git a/.travis.yml b/.travis.yml index 100a7cd8b4..7266df2d5e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,44 +1,55 @@ language: python - -python: - - "3.5" - -sudo: false - -env: - - TOX_ENV=py27-lint - - TOX_ENV=py27-docs - - TOX_ENV=py35-django19 - - TOX_ENV=py34-django19 - - TOX_ENV=py27-django19 - - TOX_ENV=py35-django18 - - TOX_ENV=py34-django18 - - TOX_ENV=py33-django18 - - TOX_ENV=py27-django18 - - TOX_ENV=py27-django110 - - TOX_ENV=py35-django110 - - TOX_ENV=py34-django110 - - TOX_ENV=py27-djangomaster - - TOX_ENV=py34-djangomaster - - TOX_ENV=py35-djangomaster - +cache: pip +dist: xenial matrix: fast_finish: true + include: + + - { 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=3.0 } + - { 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=3.0 } + - { python: "3.7", env: DJANGO=master } + + - { python: "3.8", env: DJANGO=3.0 } + - { python: "3.8", env: DJANGO=master } + + - { python: "3.8", env: TOXENV=base } + - { python: "3.8", env: TOXENV=lint } + - { python: "3.8", env: TOXENV=docs } + + - python: "3.8" + 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: TOX_ENV=py27-djangomaster - - env: TOX_ENV=py34-djangomaster - - env: TOX_ENV=py35-djangomaster + - env: DJANGO=master install: - # Virtualenv < 14 is required to keep the Python 3.2 builds running. - - pip install tox "virtualenv<14" + - pip install tox tox-venv tox-travis script: - - tox -e $TOX_ENV + - tox after_success: - pip install codecov - - codecov -e TOX_ENV + - codecov -e TOXENV,DJANGO notifications: email: false diff --git a/.tx/config b/.tx/config deleted file mode 100644 index dea9db7c93..0000000000 --- a/.tx/config +++ /dev/null @@ -1,10 +0,0 @@ -[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 415e42ac0e..2f1aad08f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ When answering questions make sure to help future contributors find their way ar 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. +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. @@ -50,7 +50,7 @@ Getting involved in triaging incoming issues is a good way to start contributing To start developing on Django REST framework, clone the repo: - git clone git@github.com:tomchristie/django-rest-framework.git + 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. @@ -59,7 +59,7 @@ Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recom 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 -r requirements.txt @@ -115,7 +115,7 @@ 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. @@ -194,14 +194,14 @@ If you want to draw attention to a note or warning, use a pair of enclosing line --- -[cite]: http://www.w3.org/People/Berners-Lee/FAQ.html +[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]: http://stackexchange.com/filters/66475/rest-framework -[issues]: https://github.com/tomchristie/django-rest-framework/issues?state=open -[pep-8]: http://www.python.org/dev/peps/pep-0008/ +[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]: http://daringfireball.net/projects/markdown/basics -[docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs +[markdown]: https://daringfireball.net/projects/markdown/basics +[docs]: https://github.com/encode/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index 55b3e531b0..566bf95436 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -3,7 +3,7 @@ - [ ] 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](http://www.django-rest-framework.org/topics/third-party-resources/#about-third-party-packages) where possible.) +- [ ] 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.) diff --git a/LICENSE.md b/LICENSE.md index aca195ec47..3dea39c363 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,16 +1,21 @@ # License -Copyright (c) 2011-2016, Tom Christie +Copyright © 2011-present, [Encode OSS Ltd](https://www.encode.io/). All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. -Redistributions in binary form must reproduce the above copyright notice, this -list of conditions and the following disclaimer in the documentation and/or -other materials provided with the distribution. +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED diff --git a/MANIFEST.in b/MANIFEST.in index 66488aae68..6f7cb8f13e 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 *.eot *.svg *.ttf *.woff -recursive-include rest_framework/templates *.html -recursive-exclude * __pycache__ -recursive-exclude * *.py[co] +recursive-include rest_framework/static *.js *.css *.png *.ico *.eot *.svg *.ttf *.woff *.woff2 +recursive-include rest_framework/templates *.html schema.js +recursive-include rest_framework/locale *.mo +global-exclude __pycache__ +global-exclude *.py[co] diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md index 49f980c932..70673c6c16 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/tomchristie/django-rest-framework/blob/master/CONTRIBUTING.md#pull-requests). +*Note*: Before submitting this pull request, please review our [contributing guidelines](https://github.com/encode/django-rest-framework/blob/master/CONTRIBUTING.md#pull-requests). ## Description diff --git a/README.md b/README.md index 155f8dead9..9591bdc17b 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,10 @@ [![build-status-image]][travis] [![coverage-status-image]][codecov] [![pypi-version]][pypi] -[![Gitter](https://badges.gitter.im/tomchristie/django-rest-framework.svg)](https://gitter.im/tomchristie/django-rest-framework?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) **Awesome web-browsable Web APIs.** -Full documentation for the project is available at [http://www.django-rest-framework.org][docs]. +Full documentation for the project is available at [https://www.django-rest-framework.org/][docs]. --- @@ -15,19 +14,21 @@ Full documentation for the project is available at [http://www.django-rest-frame 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]**. +continued development by [signing up for a paid plan][funding]. The initial aim is to provide a single full-time position on REST framework. *Every single sign-up makes a significant impact towards making that possible.* -

- - - - -

+[![][sentry-img]][sentry-url] +[![][stream-img]][stream-url] +[![][rollbar-img]][rollbar-url] +[![][cadre-img]][cadre-url] +[![][kloudless-img]][kloudless-url] +[![][esg-img]][esg-url] +[![][lightson-img]][lightson-url] +[![][retool-img]][retool-url] -*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), and [Machinalis](http://www.machinalis.com/#services).* +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], [ESG][esg-url], [Lights On Software][lightson-url], and [Retool][retool-url]. --- @@ -49,10 +50,15 @@ There is a live example API for testing purposes, [available here][sandbox]. ![Screenshot][image] +---- + # Requirements -* Python (2.7, 3.2, 3.3, 3.4, 3.5) -* Django (1.8, 1.9, 1.10) +* Python (3.5, 3.6, 3.7, 3.8) +* Django (1.11, 2.0, 2.1, 2.2, 3.0) + +We **highly recommend** and only officially support the latest patch release of +each Python and Django series. # Installation @@ -62,10 +68,10 @@ Install using `pip`... Add `'rest_framework'` to your `INSTALLED_APPS` setting. - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) + ] # Example @@ -75,7 +81,7 @@ Startup up a new project like so... pip install django pip install djangorestframework - django-admin.py startproject example . + django-admin startproject example . ./manage.py migrate ./manage.py createsuperuser @@ -91,7 +97,7 @@ from rest_framework import serializers, viewsets, routers 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. @@ -118,10 +124,10 @@ 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, @@ -138,17 +144,17 @@ That's it, we're done! You can now open the API in your browser at `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. -You can also interact with the API using command line tools such as [`curl`](http://curl.haxx.se/). For example, to list the users endpoint: +You can also interact with the API using command line tools such as [`curl`](https://curl.haxx.se/). For example, to list the users endpoint: $ curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/ - [ - { - "url": "http://127.0.0.1:8000/users/1/", - "username": "admin", - "email": "admin@example.com", - "is_staff": true, - } - ] + [ + { + "url": "http://127.0.0.1:8000/users/1/", + "username": "admin", + "email": "admin@example.com", + "is_staff": true, + } + ] Or to create a new user: @@ -162,7 +168,7 @@ Or to create a new user: # Documentation & Support -Full documentation for the project is available at [http://www.django-rest-framework.org][docs]. +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. @@ -170,34 +176,52 @@ 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**. - -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 see the [security policy][security-policy]. -[build-status-image]: https://secure.travis-ci.org/tomchristie/django-rest-framework.svg?branch=master -[travis]: http://travis-ci.org/tomchristie/django-rest-framework?branch=master -[coverage-status-image]: https://img.shields.io/codecov/c/github/tomchristie/django-rest-framework/master.svg -[codecov]: http://codecov.io/github/tomchristie/django-rest-framework?branch=master +[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 +[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.python.org/pypi/djangorestframework +[pypi]: https://pypi.org/project/djangorestframework/ [twitter]: https://twitter.com/_tomchristie [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework -[sandbox]: http://restframework.herokuapp.com/ +[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 -[oauth1-section]: http://www.django-rest-framework.org/api-guide/authentication/#django-rest-framework-oauth -[oauth2-section]: http://www.django-rest-framework.org/api-guide/authentication/#django-oauth-toolkit -[serializer-section]: http://www.django-rest-framework.org/api-guide/serializers/#serializers -[modelserializer-section]: http://www.django-rest-framework.org/api-guide/serializers/#modelserializer -[functionview-section]: http://www.django-rest-framework.org/api-guide/views/#function-based-views -[generic-views]: http://www.django-rest-framework.org/api-guide/generic-views/ -[viewsets]: http://www.django-rest-framework.org/api-guide/viewsets/ -[routers]: http://www.django-rest-framework.org/api-guide/routers/ -[serializers]: http://www.django-rest-framework.org/api-guide/serializers/ -[authentication]: http://www.django-rest-framework.org/api-guide/authentication/ -[image]: http://www.django-rest-framework.org/img/quickstart.png - -[docs]: http://www.django-rest-framework.org/ -[security-mail]: mailto:rest-framework-security@googlegroups.com +[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 +[esg-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/esg-readme.png +[lightson-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/lightson-readme.png +[retool-img]: https://raw.githubusercontent.com/encode/django-rest-framework/master/docs/img/premium/retool-readme.png + +[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/?utm_source=django&utm_medium=sponsorship&utm_campaign=freetrial +[cadre-url]: https://cadre.com/ +[kloudless-url]: https://hubs.ly/H0f30Lf0 +[esg-url]: https://software.esg-usa.com/ +[lightson-url]: https://lightsonsoftware.com +[retool-url]: https://retool.com/?utm_source=djangorest&utm_medium=sponsorship + +[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 +[serializer-section]: https://www.django-rest-framework.org/api-guide/serializers/#serializers +[modelserializer-section]: https://www.django-rest-framework.org/api-guide/serializers/#modelserializer +[functionview-section]: https://www.django-rest-framework.org/api-guide/views/#function-based-views +[generic-views]: https://www.django-rest-framework.org/api-guide/generic-views/ +[viewsets]: https://www.django-rest-framework.org/api-guide/viewsets/ +[routers]: https://www.django-rest-framework.org/api-guide/routers/ +[serializers]: https://www.django-rest-framework.org/api-guide/serializers/ +[authentication]: https://www.django-rest-framework.org/api-guide/authentication/ +[image]: https://www.django-rest-framework.org/img/quickstart.png + +[docs]: https://www.django-rest-framework.org/ +[security-policy]: https://github.com/encode/django-rest-framework/security/policy diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000..d3faefa3cb --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,9 @@ +# Security Policy + +## Reporting a Vulnerability + +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**. + +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. + +[security-mail]: mailto:rest-framework-security@googlegroups.com diff --git a/codecov.yml b/codecov.yml new file mode 100644 index 0000000000..c2336342e2 --- /dev/null +++ b/codecov.yml @@ -0,0 +1,11 @@ +coverage: + precision: 2 + round: down + range: "80...100" + + status: + project: yes + patch: no + changes: no + +comment: off diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index bf3a31eb7b..c4dbe8856f 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -1,4 +1,7 @@ -source: authentication.py +--- +source: + - authentication.py +--- # Authentication @@ -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,8 +55,8 @@ 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 = { @@ -65,8 +68,8 @@ using the `APIView` class-based views. 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. @@ -121,10 +124,10 @@ This authentication scheme uses a simple token-based HTTP Authentication scheme. 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' - ) + ] --- @@ -137,7 +140,7 @@ You'll also need to create tokens for your users. from rest_framework.authtoken.models import Token token = Token.objects.create(user=...) - print token.key + print(token.key) For clients to authenticate, the token key should be included in the `Authorization` HTTP header. The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example: @@ -205,11 +208,39 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } -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. If you need a customized version of the `obtain_auth_token` view, you can do so by overriding the `ObtainAuthToken` view class, and using that in your url conf instead. +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, 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. + +For example, you may return additional user information beyond the `token` value: + + from rest_framework.authtoken.views import ObtainAuthToken + from rest_framework.authtoken.models import Token + from rest_framework.response import Response + + class CustomAuthToken(ObtainAuthToken): + + def post(self, request, *args, **kwargs): + serializer = self.serializer_class(data=request.data, + context={'request': request}) + serializer.is_valid(raise_exception=True) + user = serializer.validated_data['user'] + token, created = Token.objects.get_or_create(user=user) + return Response({ + 'token': token.key, + 'user_id': user.pk, + 'email': user.email + }) + +And in your `urls.py`: + + urlpatterns += [ + url(r'^api-token-auth/', CustomAuthToken.as_view()) + ] + ##### With Django admin @@ -219,7 +250,22 @@ It is also possible to create Tokens manually through admin interface. In case y from rest_framework.authtoken.admin import TokenAdmin - TokenAdmin.raw_id_fields = ('user',) + TokenAdmin.raw_id_fields = ['user'] + + +#### Using Django manage.py command + +Since version 3.6.4 it's possible to generate a user token using the following command: + + ./manage.py drf_create_token + +this command will return the API token for the given user, creating it if it doesn't exist: + + Generated token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b for user user1 + +In case you want to regenerate the token (for example if it has been compromised or leaked) you can pass an additional parameter: + + ./manage.py drf_create_token -r ## SessionAuthentication @@ -239,6 +285,28 @@ If you're using an AJAX style API with SessionAuthentication, you'll need to mak 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. + +## RemoteUserAuthentication + +This authentication scheme allows you to delegate authentication to your web server, which sets the `REMOTE_USER` +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 +[Django documentation](https://docs.djangoproject.com/en/stable/howto/auth-remote-user/). + +If successfully authenticated, `RemoteUserAuthentication` provides the following credentials: + +* `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.: + +* [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) + + # Custom authentication To implement a custom authentication scheme, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method. The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise. @@ -254,9 +322,15 @@ You *may* also override the `.authenticate_header(self, request)` method. If im If the `.authenticate_header()` method is not overridden, the authentication scheme will return `HTTP 403 Forbidden` responses when an unauthenticated request is denied access. +--- + +**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 rest_framework import authentication @@ -264,7 +338,7 @@ The following example will authenticate any incoming request as the user given b 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 @@ -283,7 +357,7 @@ The following third party packages are also available. ## 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 [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**. #### Installation & configuration @@ -293,15 +367,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': ( - 'oauth2_provider.ext.rest_framework.OAuth2Authentication', - ) + '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. @@ -320,17 +394,9 @@ Install the package using `pip`. For details on configuration and usage see the Django REST framework OAuth documentation for [authentication][django-rest-framework-oauth-authentication] and [permissions][django-rest-framework-oauth-permissions]. -## Digest Authentication - -HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. [Juan Riaza][juanriaza] maintains the [djangorestframework-digestauth][djangorestframework-digestauth] package which provides HTTP digest authentication support for REST framework. - -## Django OAuth2 Consumer - -The [Django OAuth2 Consumer][doac] library from [Rediker Software][rediker] is another package that provides [OAuth 2.0 support for REST framework][doac-rest-framework]. The package includes token scoping permissions on tokens, which allows finer-grained access to your API. - ## JSON Web Token Authentication -JSON Web Token is a fairly new standard which can be used for token-based authentication. Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn't need to use a database to validate a token. [Blimp][blimp] maintains the [djangorestframework-jwt][djangorestframework-jwt] package which provides a JWT Authentication class as well as a mechanism for clients to obtain a JWT given the username and password. +JSON Web Token is a fairly new standard which can be used for token-based authentication. Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn't need to use a database to validate a token. A package for JWT authentication is [djangorestframework-simplejwt][djangorestframework-simplejwt] which provides some features as well as a pluggable token blacklist app. ## Hawk HTTP Authentication @@ -338,7 +404,7 @@ The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let y ## HTTP Signature Authentication -HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] package which provides an easy to use HTTP Signature Authentication mechanism. +HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] (outdated) package which provides an easy to use HTTP Signature Authentication mechanism. You can use the updated fork version of [djangorestframework-httpsignature][djangorestframework-httpsignature], which is [drf-httpsig][drf-httpsig]. ## Djoser @@ -356,43 +422,40 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a [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). -[cite]: http://jacobian.org/writing/rest-worst-practices/ -[http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 -[http403]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4 -[basicauth]: http://tools.ietf.org/html/rfc2617 -[oauth]: http://oauth.net/2/ +## 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. + +[cite]: https://jacobian.org/writing/rest-worst-practices/ +[http401]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 +[http403]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4 +[basicauth]: https://tools.ietf.org/html/rfc2617 [permission]: permissions.md [throttling]: throttling.md -[csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/csrf/#ajax -[mod_wsgi_official]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization +[csrf-ajax]: https://docs.djangoproject.com/en/stable/ref/csrf/#ajax +[mod_wsgi_official]: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIPassAuthorization.html [django-oauth-toolkit-getting-started]: https://django-oauth-toolkit.readthedocs.io/en/latest/rest-framework/getting_started.html -[django-rest-framework-oauth]: http://jpadilla.github.io/django-rest-framework-oauth/ -[django-rest-framework-oauth-authentication]: http://jpadilla.github.io/django-rest-framework-oauth/authentication/ -[django-rest-framework-oauth-permissions]: http://jpadilla.github.io/django-rest-framework-oauth/permissions/ +[django-rest-framework-oauth]: https://jpadilla.github.io/django-rest-framework-oauth/ +[django-rest-framework-oauth-authentication]: https://jpadilla.github.io/django-rest-framework-oauth/authentication/ +[django-rest-framework-oauth-permissions]: https://jpadilla.github.io/django-rest-framework-oauth/permissions/ [juanriaza]: https://github.com/juanriaza [djangorestframework-digestauth]: https://github.com/juanriaza/django-rest-framework-digestauth -[oauth-1.0a]: http://oauth.net/core/1.0a -[django-oauth-plus]: http://code.larlet.fr/django-oauth-plus -[django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider -[django-oauth2-provider-docs]: https://django-oauth2-provider.readthedocs.io/en/latest/ -[rfc6749]: http://tools.ietf.org/html/rfc6749 +[oauth-1.0a]: https://oauth.net/core/1.0a/ [django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit [evonove]: https://github.com/evonove/ [oauthlib]: https://github.com/idan/oauthlib -[doac]: https://github.com/Rediker-Software/doac -[rediker]: https://github.com/Rediker-Software -[doac-rest-framework]: https://github.com/Rediker-Software/doac/blob/master/docs/integrations.md# -[blimp]: https://github.com/GetBlimp -[djangorestframework-jwt]: https://github.com/GetBlimp/django-rest-framework-jwt +[djangorestframework-simplejwt]: https://github.com/davesque/django-rest-framework-simplejwt [etoccalino]: https://github.com/etoccalino/ [djangorestframework-httpsignature]: https://github.com/etoccalino/django-rest-framework-httpsignature -[amazon-http-signature]: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html +[drf-httpsig]: https://github.com/ahknight/drf-httpsig +[amazon-http-signature]: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html [http-signature-ietf-draft]: https://datatracker.ietf.org/doc/draft-cavage-http-signatures/ [hawkrest]: https://hawkrest.readthedocs.io/en/latest/ [hawk]: https://github.com/hueniverse/hawk [mohawk]: https://mohawk.readthedocs.io/en/latest/ -[mac]: http://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05 +[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 [django-rest-knox]: https://github.com/James1345/django-rest-knox +[drfpasswordless]: https://github.com/aaronn/django-rest-framework-passwordless diff --git a/docs/api-guide/caching.md b/docs/api-guide/caching.md new file mode 100644 index 0000000000..96517b15ee --- /dev/null +++ b/docs/api-guide/caching.md @@ -0,0 +1,58 @@ +# Caching + +> A certain woman had a very sharp consciousness but almost no +> memory ... She remembered enough to work, and she worked hard. +> - Lydia Davis + +Caching in REST Framework works well with the cache utilities +provided in Django. + +--- + +## Using cache with apiview and viewsets + +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]. + +```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 + +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 + @method_decorator(cache_page(60*60*2)) + @method_decorator(vary_on_cookie) + def list(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): + content = { + 'title': 'Post title', + 'body': 'Post content' + } + return Response(content) +``` + +**NOTE:** The [`cache_page`][page] decorator only caches the +`GET` and `HEAD` responses with status 200. + +[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 +[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 bd408feba5..3a4b0357fa 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 @@ -6,7 +9,7 @@ source: negotiation.py > > — [RFC 2616][cite], Fielding et al. -[cite]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html +[cite]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html Content negotiation is the process of selecting one of multiple possible representations to return to a client, based on client or server preferences. @@ -94,4 +97,4 @@ You can also set the content negotiation used for an individual view, or viewset 'accepted media type': request.accepted_renderer.media_type }) -[accept-header]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html +[accept-header]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index df8cad42df..d7d73a2f2b 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -1,4 +1,7 @@ -source: exceptions.py +--- +source: + - exceptions.py +--- # Exceptions @@ -47,7 +50,7 @@ Any example validation error might look like this: You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects. This allows you to control the style of error responses used by your API. -The function must take a pair of arguments, this first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a `Response` object, or return `None` if the exception cannot be handled. If the handler returns `None` then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response. +The function must take a pair of arguments, the first is the exception to be handled, and the second is a dictionary containing any extra context such as the view currently being handled. The exception handler function should either return a `Response` object, or return `None` if the exception cannot be handled. If the handler returns `None` then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response. For example, you might want to ensure that all error responses include the HTTP status code in the body of the response, like so: @@ -230,5 +233,33 @@ The generic views use the `raise_exception=True` flag, which means that you can By default this exception results in a response with the HTTP status code "400 Bad Request". -[cite]: http://www.doughellmann.com/articles/how-tos/python-exception-handling/index.html + +--- + +# Generic Error Views + +Django REST Framework provides two error views suitable for providing generic JSON `500` Server Error and +`400` Bad Request responses. (Django's default error views provide HTML responses, which may not be appropriate for an +API-only application.) + +Use these as per [Django's Customizing error views documentation][django-custom-error-views]. + +## `rest_framework.exceptions.server_error` + +Returns a response with status code `500` and `application/json` content type. + +Set as `handler500`: + + handler500 = 'rest_framework.exceptions.server_error' + +## `rest_framework.exceptions.bad_request` + +Returns a response with status code `400` and `application/json` content type. + +Set as `handler400`: + + handler400 = 'rest_framework.exceptions.bad_request' + +[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 diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 17168b7210..e964458f9b 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 @@ -41,25 +44,41 @@ Setting this to `False` also allows the object attribute or dictionary key to be Defaults to `True`. -### `allow_null` - -Normally an error will be raised if `None` is passed to a serializer field. Set this keyword argument to `True` if `None` should be considered a valid value. - -Defaults to `False` - ### `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. 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. + +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. +### `allow_null` + +Normally an error will be raised if `None` is passed to a serializer field. Set this keyword argument to `True` if `None` should be considered a valid value. + +Note that, without an explicit `default`, setting this argument to `True` will imply a `default` value of `null` for serialization output, but does not imply a default for input deserialization. + +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')`. +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 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. @@ -120,6 +139,15 @@ A boolean representation. When using HTML encoded form input be aware that omitting a value will always be treated as setting a field to `False`, even if it has a `default=True` option specified. This is because HTML checkbox inputs represent the unchecked state by omitting the value, so REST framework treats omission as if it is an empty checkbox input. +Note that Django 2.1 removed the `blank` kwarg from `models.BooleanField`. +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, +explicitly declare the `BooleanField` on the serializer class, or use the +`extra_kwargs` option to set the `required` flag. + Corresponds to `django.db.models.fields.BooleanField`. **Signature:** `BooleanField()` @@ -196,7 +224,7 @@ 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_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"` @@ -261,12 +289,13 @@ 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. Note that this number must be greater than or equal to decimal_places. +- `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`. #### Example usage @@ -292,10 +321,11 @@ A date and time representation. Corresponds to `django.db.models.fields.DateTimeField`. -**Signature:** `DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None)` +**Signature:** `DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None, default_timezone=None)` * `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. #### `DateTimeField` format strings. @@ -303,8 +333,6 @@ Format strings may either be [Python strftime formats][strftime] which explicitl When a value of `None` is used for the format `datetime` objects will be returned by `to_representation` and the final output representation will determined by the renderer class. -In the case of JSON this means the default datetime representation uses the [ECMA 262 date time string specification][ecma262]. This is a subset of ISO 8601 which uses millisecond precision, and includes the 'Z' suffix for the UTC timezone, for example: `2013-01-29T12:34:56.123Z`. - #### `auto_now` and `auto_now_add` model fields. When using `ModelSerializer` or `HyperlinkedModelSerializer`, note that any model fields with `auto_now=True` or `auto_now_add=True` will use serializer fields that are `read_only=True` by default. @@ -355,9 +383,10 @@ Corresponds to `django.db.models.fields.DurationField` The `validated_data` for these fields will contain a `datetime.timedelta` instance. The representation is a string following this format `'[DD] [HH:[MM:]]ss[.uuuuuu]'`. -**Note:** This field is only available with Django versions >= 1.8. +**Signature:** `DurationField(max_value=None, min_value=None)` -**Signature:** `DurationField()` +- `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. --- @@ -434,9 +463,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)` +**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. +- `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: @@ -455,9 +487,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. +- `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: @@ -468,13 +501,25 @@ You can also use the declarative style, as with `ListField`. For example: class DocumentField(DictField): child = CharField() +## HStoreField + +A preconfigured `DictField` that is compatible with Django's postgres `HStoreField`. + +**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. +- `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. + ## JSONField 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`. +- `encoder` - Use this JSON encoder to serialize input object. Defaults to `None`. --- @@ -493,7 +538,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 @@ -556,6 +601,8 @@ Note that the `WritableField` class that was present in version 2.x no longer ex ## Examples +### A Basic Custom Field + Let's look at an example of serializing a class that represents an RGB color value: class Color(object): @@ -571,8 +618,8 @@ Let's look at an example of serializing a class that represents an RGB color val """ Color objects are serialized into 'rgb(#, #, #)' notation. """ - def to_representation(self, obj): - return "rgb(%d, %d, %d)" % (obj.red, obj.green, obj.blue) + def to_representation(self, value): + return "rgb(%d, %d, %d)" % (value.red, value.green, value.blue) def to_internal_value(self, data): data = data.strip('rgb(').rstrip(')') @@ -584,24 +631,24 @@ By default field values are treated as mapping to an attribute on the object. I As an example, let's create a field that can be used to represent the class name of the object being serialized: class ClassNameField(serializers.Field): - def get_attribute(self, obj): + def get_attribute(self, instance): # We pass the object instance onto `to_representation`, # not just the field attribute. - return obj + return instance - def to_representation(self, obj): + def to_representation(self, value): """ - Serialize the object's class name. + Serialize the value's class name. """ - return obj.__class__.__name__ + return value.__class__.__name__ -#### Raising validation errors +### Raising validation errors 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__) @@ -625,7 +672,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): @@ -639,7 +686,138 @@ The `.fail()` method is a shortcut for raising `ValidationError` that takes a me return Color(red, green, blue) -This style keeps you error messages more cleanly separated from your code, and should be preferred. +This style keeps your error messages cleaner and more separated from your code, and should be preferred. + +### Using `source='*'` + +Here we'll take an example of a _flat_ `DataPoint` model with `x_coordinate` and `y_coordinate` attributes. + + class DataPoint(models.Model): + label = models.CharField(max_length=50) + x_coordinate = models.SmallIntegerField() + y_coordinate = models.SmallIntegerField() + +Using a custom field and `source='*'` we can provide a nested representation of +the coordinate pair: + + class CoordinateField(serializers.Field): + + def to_representation(self, value): + ret = { + "x": value.x_coordinate, + "y": value.y_coordinate + } + return ret + + def to_internal_value(self, data): + ret = { + "x_coordinate": data["x"], + "y_coordinate": data["y"], + } + return ret + + + class DataPointSerializer(serializers.ModelSerializer): + coordinates = CoordinateField(source='*') + + class Meta: + model = DataPoint + 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 serializer +using `source='*'`, with two `IntegerField` instances, each with their own `source` +pointing to the relevant field. + +The key points from the example, though, are: + +* `to_representation` is passed the entire `DataPoint` object and must map from that +to the desired output. + + >>> instance = DataPoint(label='Example', x_coordinate=1, y_coordinate=2) + >>> out_serializer = DataPointSerializer(instance) + >>> out_serializer.data + 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 +`to_internal_value` will update the root validated data dictionary, rather than a single key. + + >>> data = { + ... "label": "Second Example", + ... "coordinates": { + ... "x": 3, + ... "y": 4, + ... } + ... } + >>> in_serializer = DataPointSerializer(data=data) + >>> in_serializer.is_valid() + True + >>> in_serializer.validated_data + OrderedDict([('label', 'Second Example'), + ('y_coordinate', 4), + ('x_coordinate', 3)]) + +For completeness lets do the same thing again but with the nested serializer +approach suggested above: + + class NestedCoordinateSerializer(serializers.Serializer): + x = serializers.IntegerField(source='x_coordinate') + y = serializers.IntegerField(source='y_coordinate') + + + class DataPointSerializer(serializers.ModelSerializer): + coordinates = NestedCoordinateSerializer(source='*') + + class Meta: + model = DataPoint + fields = ['label', 'coordinates'] + +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 +approach. + +Serializing: + + >>> out_serializer = DataPointSerializer(instance) + >>> out_serializer.data + ReturnDict([('label', 'testing'), + ('coordinates', OrderedDict([('x', 1), ('y', 2)]))]) + +Deserializing: + + >>> in_serializer = DataPointSerializer(data=data) + >>> in_serializer.is_valid() + True + >>> in_serializer.validated_data + OrderedDict([('label', 'still testing'), + ('x_coordinate', 3), + ('y_coordinate', 4)]) + +But we also get the built-in validation for free: + + >>> invalid_data = { + ... "label": "still testing", + ... "coordinates": { + ... "x": 'a', + ... "y": 'b', + ... } + ... } + >>> invalid_serializer = DataPointSerializer(data=invalid_data) + >>> invalid_serializer.is_valid() + False + >>> invalid_serializer.errors + ReturnDict([('coordinates', + {'x': ['A valid integer is required.'], + 'y': ['A valid integer is required.']})]) + +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. + # Third party packages @@ -653,7 +831,7 @@ The [drf-compound-fields][drf-compound-fields] package provides "compound" seria The [drf-extra-fields][drf-extra-fields] package provides extra serializer fields for REST framework, including `Base64ImageField` and `PointField` classes. -## djangrestframework-recursive +## djangorestframework-recursive the [djangorestframework-recursive][djangorestframework-recursive] package provides a `RecursiveField` for serializing and deserializing recursive structures @@ -665,16 +843,16 @@ The [django-rest-framework-gis][django-rest-framework-gis] package provides geog The [django-rest-framework-hstore][django-rest-framework-hstore] package provides an `HStoreField` to support [django-hstore][django-hstore] `DictionaryField` model field. -[cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data +[cite]: https://docs.djangoproject.com/en/stable/ref/forms/api/#django.forms.Form.cleaned_data [html-and-forms]: ../topics/html-and-forms.md -[FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -[ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 -[strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior -[django-widgets]: https://docs.djangoproject.com/en/dev/ref/forms/widgets/ -[iso8601]: http://www.w3.org/TR/NOTE-datetime +[FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS +[strftime]: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior +[iso8601]: https://www.w3.org/TR/NOTE-datetime [drf-compound-fields]: https://drf-compound-fields.readthedocs.io [drf-extra-fields]: https://github.com/Hipo/drf-extra-fields [djangorestframework-recursive]: https://github.com/heywbj/django-rest-framework-recursive [django-rest-framework-gis]: https://github.com/djangonauts/django-rest-framework-gis [django-rest-framework-hstore]: https://github.com/djangonauts/django-rest-framework-hstore [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 diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 1b49d3a737..1bdb6c52ba 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -1,4 +1,7 @@ -source: filters.py +--- +source: + - filters.py +--- # Filtering @@ -92,13 +95,13 @@ 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, using the `GenericAPIView` class-based views. - import django_filters + import django_filters.rest_framework from django.contrib.auth.models import User from myapp.serializers import UserSerializer from rest_framework import generics @@ -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 @@ -127,7 +130,7 @@ Note that you can use both an overridden `.get_queryset()` and generic filtering """ model = Product serializer_class = ProductSerializer - filter_class = ProductFilter + filterset_class = ProductFilter def get_queryset(self): user = self.request.user @@ -139,17 +142,17 @@ 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`. +To use `DjangoFilterBackend`, first install `django-filter`. Then add `django_filters` to Django's `INSTALLED_APPS` pip install django-filter 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,104 +161,24 @@ Or add the filter backend to an individual View or ViewSet. class UserListView(generics.ListAPIView): ... - filter_backends = (DjangoFilterBackend,) - -If you are using the browsable API or admin API you may also want to install `django-crispy-forms`, which will enhance the presentation of the filter forms in HTML views, by allowing them to render Bootstrap 3 HTML. - - pip install django-crispy-forms - -With crispy forms installed and added to Django's `INSTALLED_APPS`, the browsable API will present a filtering control for `DjangoFilterBackend`, like so: - -![Django Filter](../img/django-filter.png) - -#### Specifying filter fields + filter_backends = [DjangoFilterBackend] -If all you need is simple equality-based filtering, you can set a `filter_fields` attribute on the view, or viewset, listing the set of fields you wish to filter against. +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 = (filters.DjangoFilterBackend,) - filter_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: http://example.com/api/products?category=clothing&in_stock=True -#### Specifying a FilterSet - -For more advanced filtering requirements you can specify a `FilterSet` class that should be used by the view. For example: - - import django_filters - from myapp.models import Product - from myapp.serializers import ProductSerializer - from rest_framework import generics - - class ProductFilter(django_filters.rest_framework.FilterSet): - min_price = django_filters.NumberFilter(name="price", lookup_expr='gte') - max_price = django_filters.NumberFilter(name="price", lookup_expr='lte') - class Meta: - model = Product - fields = ['category', 'in_stock', 'min_price', 'max_price'] - - class ProductList(generics.ListAPIView): - queryset = Product.objects.all() - serializer_class = ProductSerializer - filter_backends = (django_filters.rest_framework.DjangoFilterBackend,) - filter_class = ProductFilter - - -Which will allow you to make requests such as: - - http://example.com/api/products?category=clothing&max_price=10.00 - -You can also span relationships using `django-filter`, let's assume that each -product has foreign key to `Manufacturer` model, so we create filter that -filters using `Manufacturer` name. For example: - - import django_filters - from myapp.models import Product - from myapp.serializers import ProductSerializer - from rest_framework import generics - - class ProductFilter(django_filters.rest_framework.FilterSet): - class Meta: - model = Product - fields = ['category', 'in_stock', 'manufacturer__name'] - -This enables us to make queries like: - - http://example.com/api/products?manufacturer__name=foo - -This is nice, but it exposes the Django's double underscore convention as part of the API. If you instead want to explicitly name the filter argument you can instead explicitly include it on the `FilterSet` class: - - import django_filters - from myapp.models import Product - from myapp.serializers import ProductSerializer - from rest_framework import generics - - class ProductFilter(django_filters.rest_framework.FilterSet): - manufacturer = django_filters.CharFilter(name="manufacturer__name") - - class Meta: - model = Product - fields = ['category', 'in_stock', 'manufacturer'] - -And now you can execute: - - http://example.com/api/products?manufacturer=foo - -For more details on using filter sets see the [django-filter documentation][django-filter-docs]. - ---- - -**Hints & Tips** - -* By default filtering is not enabled. If you want to use `DjangoFilterBackend` remember to make sure it is installed by using the `'DEFAULT_FILTER_BACKENDS'` setting. -* When using boolean fields, you should use the values `True` and `False` in the URL query parameters, rather than `0`, `1`, `true` or `false`. (The allowed boolean values are currently hardwired in Django's [NullBooleanSelect implementation][nullbooleanselect].) -* `django-filter` supports filtering across relationships, using Django's double-underscore syntax. +For more advanced filtering requirements you can specify a `FilterSet` class that should be used by the view. +You can read more about `FilterSet`s in the [django-filter documentation][django-filter-docs]. +It's also recommended that you read the section on [DRF integration][django-filter-drf-docs]. ---- ## SearchFilter @@ -267,11 +190,13 @@ When in use, the browsable API will include a `SearchFilter` control: The `SearchFilter` class will only be applied if the view has a `search_fields` attribute set. The `search_fields` attribute should be a list of names of text type fields on the model, such as `CharField` or `TextField`. + from rest_framework import filters + 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: @@ -279,7 +204,7 @@ 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'] 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. @@ -292,9 +217,19 @@ The search behavior may be restricted by prepending various characters to the `s 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. + +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 -By default, the search parameter is named `'search`', but this may be overridden with the `SEARCH_PARAM` setting. + 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) For more details, see the [Django documentation][search-django-admin]. @@ -327,8 +262,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. @@ -339,7 +274,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 @@ -351,55 +286,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. - -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. @@ -432,8 +326,11 @@ The method should return a rendered HTML string. ## Pagination & schemas You can also make the filter controls available to the schema autogeneration -that REST framework provides, by implementing a `get_schema_fields()` method, -which should return a list of `coreapi.Field` instances. +that REST framework provides, by implementing a `get_schema_fields()` method. This method should have the following signature: + +`get_schema_fields(self, view)` + +The method should return a list of `coreapi.Field` instances. # Third party packages @@ -455,14 +352,10 @@ The [djangorestframework-word-filter][django-rest-framework-word-search-filter] [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. A beautiful python package `Voluptuous` is being used for validations on the incoming query parameters. The best part about voluptuous is you can define your own validations as per your query params requirements. -[cite]: https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-specific-objects-with-filters -[django-filter]: https://github.com/alex/django-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 -[guardian]: https://django-guardian.readthedocs.io/ -[view-permissions]: https://django-guardian.readthedocs.io/en/latest/userguide/assign.html -[view-permissions-blogpost]: http://blog.nyaruka.com/adding-a-view-permission-to-django-models -[nullbooleanselect]: https://github.com/django/django/blob/master/django/forms/widgets.py -[search-django-admin]: https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields +[django-filter-drf-docs]: https://django-filter.readthedocs.io/en/latest/guide/rest_framework.html +[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-word-search-filter]: https://github.com/trollknurr/django-rest-framework-word-search-filter [django-url-filter]: https://github.com/miki725/django-url-filter diff --git a/docs/api-guide/format-suffixes.md b/docs/api-guide/format-suffixes.md index 05dde47f2b..04467b3d31 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 @@ -38,7 +41,7 @@ Example: 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... @@ -90,4 +93,4 @@ It is actually a misconception. For example, take the following quote from Roy The quote does not mention Accept headers, but it does make it clear that format suffixes should be considered an acceptable pattern. [cite]: http://tech.groups.yahoo.com/group/rest-discuss/message/5857 -[cite2]: http://tech.groups.yahoo.com/group/rest-discuss/message/14844 +[cite2]: https://groups.yahoo.com/neo/groups/rest-discuss/conversations/topics/14844 diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index c368d0b468..a2f19ff2e2 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` @@ -69,7 +72,7 @@ The following attributes control the basic view behavior. The following attributes are used to control pagination when used with list views. -* `pagination_class` - The pagination class that should be used when paginating list results. Defaults to the same value as the `DEFAULT_PAGINATION_CLASS` setting, which is `'rest_framework.pagination.PageNumberPagination'`. +* `pagination_class` - The pagination class that should be used when paginating list results. Defaults to the same value as the `DEFAULT_PAGINATION_CLASS` setting, which is `'rest_framework.pagination.PageNumberPagination'`. Setting `pagination_class=None` will disable pagination on this view. **Filtering**: @@ -113,19 +116,19 @@ For example: Note that if your API doesn't include any object level permissions, you may optionally exclude the `self.check_object_permissions`, and simply return the object from the `get_object_or_404` lookup. -#### `filter_queryset(self, queryset)` +#### `filter_queryset(self, queryset)` -Given a queryset, filter it with whichever filter backends are in use, returning a new queryset. +Given a queryset, filter it with whichever filter backends are in use, returning a new queryset. -For example: +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) @@ -330,14 +333,16 @@ For example, if you need to lookup objects based on multiple fields in the URL c for field in self.lookup_fields: if self.kwargs[field]: # Ignore empty fields. filter[field] = self.kwargs[field] - return get_object_or_404(queryset, **filter) # Lookup the object + obj = get_object_or_404(queryset, **filter) # Lookup the object + self.check_object_permissions(self.request, obj) + return obj You can then simply apply this mixin to a view or viewset anytime you need to apply the custom behavior. 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. @@ -373,21 +378,16 @@ 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. -[cite]: https://docs.djangoproject.com/en/dev/ref/class-based-views/#base-vs-generic-views +[cite]: https://docs.djangoproject.com/en/stable/ref/class-based-views/#base-vs-generic-views [GenericAPIView]: #genericapiview [ListModelMixin]: #listmodelmixin [CreateModelMixin]: #createmodelmixin [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/Axiologue/DjangoRestMultipleModels +[django-rest-multiple-models]: https://github.com/MattBroach/DjangoRestMultipleModels diff --git a/docs/api-guide/metadata.md b/docs/api-guide/metadata.md index e12aeb7fd0..fdb7786266 100644 --- a/docs/api-guide/metadata.md +++ b/docs/api-guide/metadata.md @@ -1,4 +1,7 @@ -source: metadata.py +--- +source: + - metadata.py +--- # Metadata @@ -67,7 +70,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. - @list_route(methods=['GET']) + @action(methods=['GET'], detail=False) def schema(self, request): meta = self.metadata_class() data = meta.determine_metadata(request, self) @@ -104,6 +107,18 @@ Then configure your settings to use this custom class: 'DEFAULT_METADATA_CLASS': 'myproject.apps.core.MinimalMetadata' } -[cite]: http://tools.ietf.org/html/rfc7231#section-4.3.7 +# Third party packages + +The following third party packages provide additional metadata implementations. + +## DRF-schema-adapter + +[drf-schema-adapter][drf-schema-adapter] is a set of tools that makes it easier to provide schema information to frontend frameworks and libraries. It provides a metadata mixin as well as 2 metadata classes and several adapters suitable to generate [json-schema][json-schema] as well as schema information readable by various libraries. + +You can also write your own adapter to work with your specific frontend. +If you wish to do so, it also provides an exporter that can export those schema information to json files. + +[cite]: https://tools.ietf.org/html/rfc7231#section-4.3.7 [no-options]: https://www.mnot.net/blog/2012/10/29/NO_OPTIONS -[json-schema]: http://json-schema.org/ +[json-schema]: https://json-schema.org/ +[drf-schema-adapter]: https://github.com/drf-forms/drf-schema-adapter diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index f82614eca7..8d9eb22881 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -1,4 +1,7 @@ -source: pagination.py +--- +source: + - pagination.py +--- # Pagination @@ -21,14 +24,14 @@ Pagination can be turned off by setting the pagination class to `None`. ## Setting the pagination style -The default pagination style may be set globally, using the `DEFAULT_PAGINATION_CLASS` and `PAGE_SIZE` setting keys. For example, to use the built-in limit/offset pagination, you would do something like this: +The pagination style may be set globally, using the `DEFAULT_PAGINATION_CLASS` and `PAGE_SIZE` setting keys. For example, to use the built-in limit/offset pagination, you would do something like this: REST_FRAMEWORK = { 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination', 'PAGE_SIZE': 100 } -Note that you need to set both the pagination class, and the page size that should be used. +Note that you need to set both the pagination class, and the page size that should be used. Both `DEFAULT_PAGINATION_CLASS` and `PAGE_SIZE` are `None` by default. You can also set the pagination class on an individual view by using the `pagination_class` attribute. Typically you'll want to use the same pagination style throughout your API, although you might want to vary individual aspects of the pagination, such as default or maximum page size, on a per-view basis. @@ -46,7 +49,7 @@ If you want to modify particular aspects of the pagination style, you'll want to page_size_query_param = 'page_size' max_page_size = 1000 -You can then apply your new style to a view using the `.pagination_class` attribute: +You can then apply your new style to a view using the `pagination_class` attribute: class BillingRecordsView(generics.ListAPIView): queryset = Billing.objects.all() @@ -85,7 +88,7 @@ This pagination style accepts a single number page number in the request query p #### Setup -To enable the `PageNumberPagination` style globally, use the following configuration, modifying the `PAGE_SIZE` as desired: +To enable the `PageNumberPagination` style globally, use the following configuration, and set the `PAGE_SIZE` as desired: REST_FRAMEWORK = { 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', @@ -179,6 +182,10 @@ Proper usage of cursor pagination should have an ordering field that satisfies t * Should be an unchanging value, such as a timestamp, slug, or other field that is only set once, on creation. * Should be unique, or nearly unique. Millisecond precision timestamps are a good example. This implementation of cursor pagination uses a smart "position plus offset" style that allows it to properly support not-strictly-unique values as the ordering. * Should be a non-nullable value that can be coerced to a string. +* Should not be a float. Precision errors easily lead to incorrect results. + Hint: use decimals instead. + (If you already have a float field and must paginate on that, an + [example `CursorPagination` subclass that uses decimals to limit precision is available here][float_cursor_pagination_example].) * The field should have a database index. Using an ordering field that does not satisfy these constraints will generally still work, but you'll be losing some of the benefits of cursor pagination. @@ -226,8 +233,8 @@ Suppose we want to replace the default pagination output style with a modified f def get_paginated_response(self, data): return Response({ 'links': { - 'next': self.get_next_link(), - 'previous': self.get_previous_link() + 'next': self.get_next_link(), + 'previous': self.get_previous_link() }, 'count': self.page.paginator.count, 'results': data @@ -242,29 +249,6 @@ We'd then need to setup the custom class in our configuration: Note that if you care about how the ordering of keys is displayed in responses in the browsable API you might choose to use an `OrderedDict` when constructing the body of paginated responses, but this is optional. -## Header based pagination - -Let's modify the built-in `PageNumberPagination` style, so that instead of include the pagination links in the body of the response, we'll instead include a `Link` header, in a [similar style to the GitHub API][github-link-pagination]. - - class LinkHeaderPagination(pagination.PageNumberPagination): - def get_paginated_response(self, data): - next_url = self.get_next_link() - previous_url = self.get_previous_link() - - if next_url is not None and previous_url is not None: - link = '<{next_url}>; rel="next", <{previous_url}>; rel="prev"' - elif next_url is not None: - link = '<{next_url}>; rel="next"' - elif previous_url is not None: - link = '<{previous_url}>; rel="prev"' - else: - link = '' - - link = link.format(next_url=next_url, previous_url=previous_url) - headers = {'Link': link} if link else {} - - return Response(data, headers=headers) - ## Using your custom pagination class To have your custom pagination class be used by default, use the `DEFAULT_PAGINATION_CLASS` setting: @@ -276,17 +260,18 @@ 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 -that REST framework provides, by implementing a `get_schema_fields()` method, -which should return a list of `coreapi.Field` instances. +that REST framework provides, by implementing a `get_schema_fields()` method. This method should have the following signature: ---- +`get_schema_fields(self, view)` -![Link Header][link-header] - -*A custom pagination style, using the 'Link' header'* +The method should return a list of `coreapi.Field` instances. --- @@ -325,10 +310,15 @@ The [`DRF-extensions` package][drf-extensions] includes a [`PaginateByMaxMixin` The [`drf-proxy-pagination` package][drf-proxy-pagination] includes a `ProxyPagination` class which allows to choose pagination class with a query parameter. -[cite]: https://docs.djangoproject.com/en/dev/topics/pagination/ -[github-link-pagination]: https://developer.github.com/guides/traversing-with-pagination/ +## 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). + +[cite]: https://docs.djangoproject.com/en/stable/topics/pagination/ [link-header]: ../img/link-header-pagination.png -[drf-extensions]: http://chibisov.github.io/drf-extensions/docs/ -[paginate-by-max-mixin]: http://chibisov.github.io/drf-extensions/docs/#paginatebymaxmixin +[drf-extensions]: https://chibisov.github.io/drf-extensions/docs/ +[paginate-by-max-mixin]: https://chibisov.github.io/drf-extensions/docs/#paginatebymaxmixin [drf-proxy-pagination]: https://github.com/tuffnatty/drf-proxy-pagination -[disqus-cursor-api]: http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api +[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 diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index ef2859fe16..a3bc74a2ba 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -1,4 +1,7 @@ -source: parsers.py +--- +source: + - parsers.py +--- # Parsers @@ -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}) @@ -54,9 +57,10 @@ Or, if you're using the `@api_view` decorator with function based views. from rest_framework.decorators import api_view from rest_framework.decorators import parser_classes + 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. @@ -101,7 +105,7 @@ If it is called without a `filename` URL keyword argument, then the client must ##### Notes: -* The `FileUploadParser` is for usage with native clients that can upload the file as a raw data request. For web-based uploads, or for native clients with multipart upload support, you should use the `MultiPartParser` parser instead. +* The `FileUploadParser` is for usage with native clients that can upload the file as a raw data request. For web-based uploads, or for native clients with multipart upload support, you should use the `MultiPartParser` instead. * Since this parser's `media_type` matches any content type, `FileUploadParser` should generally be the only parser set on an API view. * `FileUploadParser` respects Django's standard `FILE_UPLOAD_HANDLERS` setting, and the `request.upload_handlers` attribute. See the [Django documentation][upload-handlers] for more details. @@ -109,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'] @@ -185,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 @@ -206,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 @@ -222,11 +226,11 @@ Modify your REST framework settings. [djangorestframework-camel-case] provides camel case JSON renderers and parsers for REST framework. This allows serializers to use Python-style underscored field names, but be exposed in the API as Javascript-style camel case field names. It is maintained by [Vitaly Babiy][vbabiy]. -[jquery-ajax]: http://api.jquery.com/jQuery.ajax/ +[jquery-ajax]: https://api.jquery.com/jQuery.ajax/ [cite]: https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion -[upload-handlers]: https://docs.djangoproject.com/en/dev/topics/http/file-uploads/#upload-handlers -[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/ -[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/ +[upload-handlers]: https://docs.djangoproject.com/en/stable/topics/http/file-uploads/#upload-handlers +[rest-framework-yaml]: https://jpadilla.github.io/django-rest-framework-yaml/ +[rest-framework-xml]: https://jpadilla.github.io/django-rest-framework-xml/ [yaml]: http://www.yaml.org/ [messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack [juanriaza]: https://github.com/juanriaza diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 7cdb595313..25baa4813d 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -1,4 +1,7 @@ -source: permissions.py +--- +source: + - permissions.py +--- # Permissions @@ -10,9 +13,9 @@ Together with [authentication] and [throttling], permissions determine whether a Permission checks are always run at the very start of the view, before any other code is allowed to proceed. Permission checks will typically use the authentication information in the `request.user` and `request.auth` properties to determine if the incoming request should be permitted. -Permissions are used to grant or deny access different classes of users to different parts of the API. +Permissions are used to grant or deny access for different classes of users to different parts of the API. -The simplest style of permission would be to allow access to any authenticated user, and deny access to any unauthenticated user. This corresponds the `IsAuthenticated` class in REST framework. +The simplest style of permission would be to allow access to any authenticated user, and deny access to any unauthenticated user. This corresponds to the `IsAuthenticated` class in REST framework. A slightly less strict style of permission would be to allow full access to authenticated users, but allow read-only access to unauthenticated users. This corresponds to the `IsAuthenticatedOrReadOnly` class in REST framework. @@ -44,10 +47,23 @@ This will either raise a `PermissionDenied` or `NotAuthenticated` exception, or For example: def get_object(self): - obj = get_object_or_404(self.get_queryset()) + obj = get_object_or_404(self.get_queryset(), pk=self.kwargs["pk"]) self.check_object_permissions(self.request, obj) return obj +--- + +**Note**: With the exception of `DjangoObjectPermissions`, the provided +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 +permissions, **you must** subclass them and implement the +`has_object_permission()` method described in the [_Custom +permissions_](#custom-permissions) section (below). + +--- + #### Limitations of object level permissions For performance reasons the generic views will not automatically apply object level permissions to each instance in a queryset when returning a list of objects. @@ -59,16 +75,16 @@ Often when you're using object level permissions you'll also want to [filter the 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. @@ -78,7 +94,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 = { @@ -93,7 +109,7 @@ 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' @@ -102,6 +118,27 @@ Or, if you're using the `@api_view` decorator with function based views. __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. +Provided they inherit from `rest_framework.permissions.BasePermission`, permissions can be composed using standard Python bitwise operators. For example, `IsAuthenticatedOrReadOnly` could be written: + + from rest_framework.permissions import BasePermission, IsAuthenticated, SAFE_METHODS + from rest_framework.response import Response + from rest_framework.views import APIView + + class ReadOnly(BasePermission): + def has_permission(self, request, view): + return request.method in SAFE_METHODS + + class ExampleView(APIView): + permission_classes = [IsAuthenticated|ReadOnly] + + def get(self, request, format=None): + content = { + 'status': 'request was permitted' + } + return Response(content) + +__Note:__ it supports & (and), | (or) and ~ (not). + --- # API Reference @@ -164,13 +201,11 @@ As with `DjangoModelPermissions`, this permission must only be applied to views Note that `DjangoObjectPermissions` **does not** require the `django-guardian` package, and should support other object-level backends equally well. -As with `DjangoModelPermissions` you can use custom model permissions by overriding `DjangoModelPermissions` and setting the `.perms_map` property. Refer to the source code for details. +As with `DjangoModelPermissions` you can use custom model permissions by overriding `DjangoObjectPermissions` and setting the `.perms_map` property. Refer to the source code for details. --- -**Note**: If you need object level `view` permissions for `GET`, `HEAD` and `OPTIONS` requests, you'll want to consider also adding the `DjangoObjectPermissionsFilter` class to ensure that list endpoints only return results including objects for which the user has appropriate view permissions. - ---- +**Note**: If you need object level `view` permissions for `GET`, `HEAD` and `OPTIONS` requests and are using django-guardian for your object-level permissions backend, you'll want to consider using the `DjangoObjectPermissionsFilter` class provided by the [`djangorestframework-guardian` package][django-rest-framework-guardian]. It ensures that list endpoints only return results including objects for which the user has appropriate view permissions. --- @@ -192,20 +227,20 @@ If you need to test if a request is a read operation or a write operation, you s --- -**Note**: The instance-level `has_object_permission` method will only be called if the view-level `has_permission` checks have already passed. Also note that in order for the instance-level checks to run, the view code should explicitly call `.check_object_permissions(request, obj)`. If you are using the generic views then this will be handled for you by default. +**Note**: The instance-level `has_object_permission` method will only be called if the view-level `has_permission` checks have already passed. Also note that in order for the instance-level checks to run, the view code should explicitly call `.check_object_permissions(request, obj)`. If you are using the generic views then this will be handled for you by default. (Function-based views will need to check object permissions explicitly, raising `PermissionDenied` on failure.) --- 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. - + from rest_framework import permissions class CustomerAccessPermission(permissions.BasePermission): message = 'Adding customers not allowed.' - + def has_permission(self, request, view): ... - + ## 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. @@ -249,34 +284,47 @@ Also note that the generic views will only check the object-level permissions fo 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. ## REST Condition -The [REST Condition][rest-condition] package is another extension for building complex permissions in a simple and convenient way. The extension allows you to combine permissions with logical operators. +The [REST Condition][rest-condition] package is another extension for building complex permissions in a simple and convenient way. The extension allows you to combine permissions with logical operators. ## DRY Rest Permissions -The [DRY Rest Permissions][dry-rest-permissions] package provides the ability to define different permissions for individual default and custom actions. This package is made for apps with permissions that are derived from relationships defined in the app's data model. It also supports permission checks being returned to a client app through the API's serializer. Additionally it supports adding permissions to the default and custom list actions to restrict the data they retrive per user. +The [DRY Rest Permissions][dry-rest-permissions] package provides the ability to define different permissions for individual default and custom actions. This package is made for apps with permissions that are derived from relationships defined in the app's data model. It also supports permission checks being returned to a client app through the API's serializer. Additionally it supports adding permissions to the default and custom list actions to restrict the data they retrieve per user. ## Django Rest Framework Roles The [Django Rest Framework Roles][django-rest-framework-roles] package makes it easier to parameterize your API over multiple types of users. +## Django REST Framework API Key + +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. + [cite]: https://developer.apple.com/library/mac/#documentation/security/Conceptual/AuthenticationAndAuthorizationGuide/Authorization/Authorization.html [authentication]: authentication.md [throttling]: throttling.md [filtering]: filtering.md -[contribauth]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#custom-permissions -[objectpermissions]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#handling-object-permissions +[contribauth]: https://docs.djangoproject.com/en/stable/topics/auth/customizing/#custom-permissions +[objectpermissions]: https://docs.djangoproject.com/en/stable/topics/auth/customizing/#handling-object-permissions [guardian]: https://github.com/lukaszb/django-guardian -[get_objects_for_user]: http://pythonhosted.org/django-guardian/api/guardian.shortcuts.html#get-objects-for-user -[2.2-announcement]: ../topics/2.2-announcement.md [filtering]: filtering.md -[drf-any-permissions]: https://github.com/kevin-brown/drf-any-permissions [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 [django-rest-framework-roles]: https://github.com/computer-lab/django-rest-framework-roles +[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 diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index aabe49412b..ef6efec5ea 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -1,12 +1,13 @@ -source: relations.py +--- +source: + - relations.py +--- # Serializer relations -> Bad programmers worry about the code. -> Good programmers worry about data structures and their relationships. +> Data structures, not algorithms, are central to programming. > -> — [Linus Torvalds][cite] - +> — [Rob Pike][cite] Relational fields are used to represent model relationships. They can be applied to `ForeignKey`, `ManyToManyField` and `OneToOneField` relationships, as well as to reverse relationships, and custom relationships such as `GenericForeignKey`. @@ -24,7 +25,7 @@ To do so, open the Django shell, using `python manage.py shell`, then import the >>> from myapp.serializers import AccountSerializer >>> serializer = AccountSerializer() - >>> print repr(serializer) # Or `print(repr(serializer))` in Python 3.x. + >>> print(repr(serializer)) AccountSerializer(): id = IntegerField(label='ID', read_only=True) name = CharField(allow_blank=True, max_length=100, required=False) @@ -45,15 +46,15 @@ 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 __unicode__(self): + def __str__(self): return '%d: %s' % (self.order, self.title) ## StringRelatedField -`StringRelatedField` may be used to represent the target of the relationship using its `__unicode__` method. +`StringRelatedField` may be used to represent the target of the relationship using its `__str__` method. For example, the following serializer. @@ -62,7 +63,7 @@ For example, the following serializer. class Meta: model = Album - fields = ('album_name', 'artist', 'tracks') + fields = ['album_name', 'artist', 'tracks'] Would serialize to the following representation. @@ -94,7 +95,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: @@ -134,7 +135,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: @@ -186,7 +187,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: @@ -221,7 +222,7 @@ This field can be applied as an identity relationship, such as the `'url'` field class Meta: model = Album - fields = ('album_name', 'artist', 'track_listing') + fields = ['album_name', 'artist', 'track_listing'] Would serialize to a representation like this: @@ -244,7 +245,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. @@ -255,14 +258,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: @@ -293,14 +296,14 @@ By default nested serializers are read-only. If you want to support write-operat 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') @@ -354,7 +357,7 @@ 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. @@ -384,7 +387,7 @@ The `get_url` method is used to map the object instance to its URL representatio May raise a `NoReverseMatch` if the `view_name` and `lookup_field` attributes are not configured to correctly match the URL conf. -**get_object(self, queryset, view_name, view_args, view_kwargs)** +**get_object(self, view_name, view_args, view_kwargs)** If you want to support a writable hyperlinked field then you'll also want to override `get_object`, in order to map incoming URLs back to the object they represent. For read-only hyperlinked fields there is no need to override this method. @@ -479,7 +482,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: @@ -491,7 +494,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. @@ -505,14 +508,14 @@ For example, given the following model for a tag, which has a generic relationsh """ Tags arbitrary model instances using a generic relation. - See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/ + See: https://docs.djangoproject.com/en/stable/ref/contrib/contenttypes/ """ tag_name = models.SlugField() content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE) object_id = models.PositiveIntegerField() tagged_object = GenericForeignKey('content_type', 'object_id') - def __unicode__(self): + def __str__(self): return self.tag_name And the following two models, which may have associated tags: @@ -578,6 +581,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 @@ -592,10 +597,11 @@ The [drf-nested-routers package][drf-nested-routers] provides routers and relati The [rest-framework-generic-relations][drf-nested-relations] library provides read/write serialization for generic foreign keys. -[cite]: http://lwn.net/Articles/193245/ -[reverse-relationships]: https://docs.djangoproject.com/en/dev/topics/db/queries/#following-relationships-backward -[routers]: http://www.django-rest-framework.org/api-guide/routers#defaultrouter -[generic-relations]: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/#id1 -[2.2-announcement]: ../topics/2.2-announcement.md +[cite]: http://users.ece.utexas.edu/~adnan/pike.html +[reverse-relationships]: https://docs.djangoproject.com/en/stable/topics/db/queries/#following-relationships-backward +[routers]: https://www.django-rest-framework.org/api-guide/routers#defaultrouter +[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/2.2/topics/db/models/#intermediary-manytomany +[dealing-with-nested-objects]: https://www.django-rest-framework.org/api-guide/serializers/#dealing-with-nested-objects diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index a95778350e..a3321e8601 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. @@ -89,7 +92,7 @@ The default JSON encoding style can be altered using the `UNICODE_JSON` and `COM **.media_type**: `application/json` -**.format**: `'.json'` +**.format**: `'json'` **.charset**: `None` @@ -113,7 +116,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() @@ -123,9 +126,11 @@ You can use `TemplateHTMLRenderer` either to return regular HTML pages using RES If you're building websites that use `TemplateHTMLRenderer` along with other renderer classes, you should consider listing `TemplateHTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritised first even for browsers that send poorly formed `ACCEPT:` headers. +See the [_HTML & Forms_ Topic Page][html-and-forms] for further examples of `TemplateHTMLRenderer` usage. + **.media_type**: `text/html` -**.format**: `'.html'` +**.format**: `'html'` **.charset**: `utf-8` @@ -137,8 +142,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) @@ -147,7 +152,7 @@ You can use `StaticHTMLRenderer` either to return regular HTML pages using REST **.media_type**: `text/html` -**.format**: `'.html'` +**.format**: `'html'` **.charset**: `utf-8` @@ -163,7 +168,7 @@ This renderer will determine which other renderer would have been given highest **.media_type**: `text/html` -**.format**: `'.api'` +**.format**: `'api'` **.charset**: `utf-8` @@ -198,7 +203,7 @@ Note that views that have nested or list serializers for their input won't work **.media_type**: `text/html` -**.format**: `'.admin'` +**.format**: `'admin'` **.charset**: `utf-8` @@ -222,7 +227,7 @@ For more information see the [HTML & Forms][html-and-forms] documentation. **.media_type**: `text/html` -**.format**: `'.form'` +**.format**: `'form'` **.charset**: `utf-8` @@ -234,7 +239,7 @@ This renderer is used for rendering HTML multipart form data. **It is not suita **.media_type**: `multipart/form-data; boundary=BoUnDaRyStRiNg` -**.format**: `'.multipart'` +**.format**: `'multipart'` **.charset**: `utf-8` @@ -323,8 +328,8 @@ In some cases you might want your view to use different serialization styles dep 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 @@ -396,12 +401,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 @@ -417,12 +422,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 @@ -446,15 +451,52 @@ 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) + +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. + +#### Installation & configuration + +Install using pip. + + $ pip install drf-renderer-xlsx + +Modify your REST framework settings. + + REST_FRAMEWORK = { + ... + + 'DEFAULT_RENDERER_CLASSES': [ + 'rest_framework.renderers.JSONRenderer', + 'rest_framework.renderers.BrowsableAPIRenderer', + 'drf_renderer_xlsx.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 .models import MyExampleModel + from .serializers import MyExampleSerializer + + class MyExampleViewSet(XLSXFileMixin, ReadOnlyModelViewSet): + queryset = MyExampleModel.objects.all() + serializer_class = MyExampleSerializer + renderer_classes = [XLSXRenderer] + filename = 'my_export.xlsx' + ## CSV Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework. @@ -476,28 +518,31 @@ 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/dev/ref/template-response/#the-rendering-process +[cite]: https://docs.djangoproject.com/en/stable/stable/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 [testing]: testing.md [HATEOAS]: http://timelessrepo.com/haters-gonna-hateoas -[quote]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven -[application/vnd.github+json]: http://developer.github.com/v3/media/ +[quote]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[application/vnd.github+json]: https://developer.github.com/v3/media/ [application/vnd.collection+json]: http://www.amundsen.com/media-types/collection/ -[django-error-views]: https://docs.djangoproject.com/en/dev/topics/http/views/#customizing-error-views -[rest-framework-jsonp]: http://jpadilla.github.io/django-rest-framework-jsonp/ -[cors]: http://www.w3.org/TR/cors/ -[cors-docs]: http://www.django-rest-framework.org/topics/ajax-csrf-cors/ -[jsonp-security]: http://stackoverflow.com/questions/613962/is-jsonp-safe-to-use -[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/ -[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/ -[messagepack]: http://msgpack.org/ +[django-error-views]: https://docs.djangoproject.com/en/stable/topics/http/views/#customizing-error-views +[rest-framework-jsonp]: https://jpadilla.github.io/django-rest-framework-jsonp/ +[cors]: https://www.w3.org/TR/cors/ +[cors-docs]: https://www.django-rest-framework.org/topics/ajax-csrf-cors/ +[jsonp-security]: https://stackoverflow.com/questions/613962/is-jsonp-safe-to-use +[rest-framework-yaml]: https://jpadilla.github.io/django-rest-framework-yaml/ +[rest-framework-xml]: https://jpadilla.github.io/django-rest-framework-xml/ +[messagepack]: https://msgpack.org/ [juanriaza]: https://github.com/juanriaza [mjumbewu]: https://github.com/mjumbewu +[flipperpa]: https://github.com/flipperpa +[wharton]: https://github.com/wharton +[drf-renderer-xlsx]: https://github.com/wharton/drf-renderer-xlsx [vbabiy]: https://github.com/vbabiy -[rest-framework-yaml]: http://jpadilla.github.io/django-rest-framework-yaml/ -[rest-framework-xml]: http://jpadilla.github.io/django-rest-framework-xml/ +[rest-framework-yaml]: https://jpadilla.github.io/django-rest-framework-yaml/ +[rest-framework-xml]: https://jpadilla.github.io/django-rest-framework-xml/ [yaml]: http://www.yaml.org/ [djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack [djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv @@ -506,7 +551,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily [drf-ujson-renderer]: https://github.com/gizmag/drf-ujson-renderer [djangorestframework-camel-case]: https://github.com/vbabiy/djangorestframework-camel-case [Django REST Pandas]: https://github.com/wq/django-rest-pandas -[Pandas]: http://pandas.pydata.org/ +[Pandas]: https://pandas.pydata.org/ [other formats]: https://github.com/wq/django-rest-pandas#supported-formats [sheppard]: https://github.com/sheppard [wq]: https://github.com/wq diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 393b1ab9ac..1c336953ca 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -1,4 +1,7 @@ -source: request.py +--- +source: + - request.py +--- # Requests @@ -46,11 +49,11 @@ 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 behaviour such as selecting a different serialization schemes for different media types. ## .accepted_renderer -The renderer instance what was selected by the content negotiation stage. +The renderer instance that was selected by the content negotiation stage. ## .accepted_media_type @@ -90,6 +93,10 @@ 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` 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. + +--- + # Browser enhancements REST framework supports a few browser enhancements such as browser-based `PUT`, `PATCH` and `DELETE` forms. diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index 97f3127106..dbdc8ff2cc 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -1,4 +1,7 @@ -source: response.py +--- +source: + - response.py +--- # Responses @@ -42,7 +45,7 @@ Arguments: ## .data -The unrendered content of a `Request` object. +The unrendered, serialized data of the response. ## .status_code @@ -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/dev/ref/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 35d88e2db1..70df42b8f0 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 @@ -50,6 +53,6 @@ As with the `reverse` function, you should **include the request as a keyword ar api_root = reverse_lazy('api-root', request=request) -[cite]: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5 -[reverse]: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse -[reverse-lazy]: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy +[cite]: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5 +[reverse]: https://docs.djangoproject.com/en/stable/topics/http/urls/#reverse +[reverse-lazy]: https://docs.djangoproject.com/en/stable/topics/http/urls/#reverse-lazy diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index 10a86bdf0e..5f6802222f 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -1,4 +1,7 @@ -source: routers.py +--- +source: + - routers.py +--- # Routers @@ -28,7 +31,7 @@ There are two mandatory arguments to the `register()` method: Optionally, you may also specify an additional argument: -* `base_name` - The base to use for the URL names that are created. If unset the basename will be automatically generated based on the `queryset` attribute of the viewset, if it has one. Note that if the viewset does not include a `queryset` attribute then you must set `base_name` when registering the viewset. +* `basename` - The base to use for the URL names that are created. If unset the basename will be automatically generated based on the `queryset` attribute of the viewset, if it has one. Note that if the viewset does not include a `queryset` attribute then you must set `basename` when registering the viewset. The example above would generate the following URL patterns: @@ -39,13 +42,13 @@ The example above would generate the following URL patterns: --- -**Note**: The `base_name` argument is used to specify the initial part of the view name pattern. In the example above, that's the `user` or `account` part. +**Note**: The `basename` argument is used to specify the initial part of the view name pattern. In the example above, that's the `user` or `account` part. -Typically you won't *need* to specify the `base_name` argument, but if you have a viewset where you've defined a custom `get_queryset` method, then the viewset may not have a `.queryset` attribute set. If you try to register that viewset you'll see an error like this: +Typically you won't *need* to specify the `basename` argument, but if you have a viewset where you've defined a custom `get_queryset` method, then the viewset may not have a `.queryset` attribute set. If you try to register that viewset you'll see an error like this: - 'base_name' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.queryset' attribute. + 'basename' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.queryset' attribute. -This means you'll need to explicitly set the `base_name` argument when registering the viewset, as it could not be automatically determined from the model name. +This means you'll need to explicitly set the `basename` argument when registering the viewset, as it could not be automatically determined from the model name. --- @@ -53,89 +56,108 @@ This means you'll need to explicitly set the `base_name` argument when registeri The `.urls` attribute on a router instance is simply a standard list of URL patterns. There are a number of different styles for how you can include these URLs. -For example, you can append `router.urls` to a list of existing views… +For example, you can append `router.urls` to a list of existing views... router = routers.SimpleRouter() router.register(r'users', UserViewSet) router.register(r'accounts', AccountViewSet) - + urlpatterns = [ url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), ] - + urlpatterns += router.urls -Alternatively you can use Django's `include` function, like so… +Alternatively you can use Django's `include` function, like so... urlpatterns = [ url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), url(r'^', include(router.urls)), ] -Router URL patterns can also be namespaces. +You may use `include` with an application namespace: + + urlpatterns = [ + url(r'^forgot-password/$', ForgotPasswordFormView.as_view()), + url(r'^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, namespace='api')), + url(r'^api/', include((router.urls, 'app_name'), namespace='instance_name')), ] -If using namespacing with hyperlinked serializers you'll also need to ensure that any `view_name` parameters on the serializers correctly reflect the namespace. In the example above you'd need to include a parameter such as `view_name='api:user-detail'` for serializer fields hyperlinked to the user detail view. +See Django's [URL namespaces docs][url-namespace-docs] and the [`include` API reference][include-api-reference] for more details. + +--- + +**Note**: If using namespacing with hyperlinked serializers you'll also need to ensure that any `view_name` parameters +on the serializers correctly reflect the namespace. In the examples above you'd need to include a parameter such as +`view_name='app_name:user-detail'` for serializer fields hyperlinked to the user detail view. + +The automatic `view_name` generation uses a pattern like `%(model_name)-detail`. Unless your models names actually clash +you may be better off **not** namespacing your Django REST Framework views when using hyperlinked serializers. + +--- -### Extra link and actions +### Routing for extra actions -Any methods on the viewset decorated with `@detail_route` or `@list_route` will also be routed. -For example, given a method like this on the `UserViewSet` class: +A viewset may [mark extra actions for routing][route-decorators] by decorating a method with the `@action` decorator. These extra actions will be included in the generated routes. For example, given the `set_password` method on the `UserViewSet` class: from myapp.permissions import IsAdminOrIsSelf - from rest_framework.decorators import detail_route + from rest_framework.decorators import action class UserViewSet(ModelViewSet): ... - @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf]) + @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf]) def set_password(self, request, pk=None): ... -The following URL pattern would additionally be generated: +The following route would be generated: -* URL pattern: `^users/{pk}/set_password/$` Name: `'user-set-password'` +* URL pattern: `^users/{pk}/set_password/$` +* URL name: `'user-set-password'` -If you do not want to use the default URL generated for your custom action, you can instead use the url_path parameter to customize it. +By default, the URL pattern is based on the method name, and the URL name is the combination of the `ViewSet.basename` and the hyphenated method name. +If you don't want to use the defaults for either of these values, you can instead provide the `url_path` and `url_name` arguments to the `@action` decorator. For example, if you want to change the URL for our custom action to `^users/{pk}/change-password/$`, you could write: from myapp.permissions import IsAdminOrIsSelf - from rest_framework.decorators import detail_route - + from rest_framework.decorators import action + class UserViewSet(ModelViewSet): ... - - @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf], url_path='change-password') + + @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf], + url_path='change-password', url_name='change_password') def set_password(self, request, pk=None): ... The above example would now generate the following URL pattern: -* URL pattern: `^users/{pk}/change-password/$` Name: `'user-change-password'` - -For more information see the viewset documentation on [marking extra actions for routing][route-decorators]. +* URL path: `^users/{pk}/change-password/$` +* URL name: `'user-change_password'` # API Guide ## SimpleRouter -This router includes routes for the standard set of `list`, `create`, `retrieve`, `update`, `partial_update` and `destroy` actions. The viewset can also mark additional methods to be routed, using the `@detail_route` or `@list_route` decorators. +This router includes routes for the standard set of `list`, `create`, `retrieve`, `update`, `partial_update` and `destroy` actions. The viewset can also mark additional methods to be routed, using the `@action` decorator. - + - +
URL StyleHTTP MethodActionURL Name
{prefix}/GETlist{basename}-list
POSTcreate
{prefix}/{methodname}/GET, or as specified by `methods` argument`@list_route` decorated method{basename}-{methodname}
{prefix}/{url_path}/GET, or as specified by `methods` argument`@action(detail=False)` decorated method{basename}-{url_name}
{prefix}/{lookup}/GETretrieve{basename}-detail
PUTupdate
PATCHpartial_update
DELETEdestroy
{prefix}/{lookup}/{methodname}/GET, or as specified by `methods` argument`@detail_route` decorated method{basename}-{methodname}
{prefix}/{lookup}/{url_path}/GET, or as specified by `methods` argument`@action(detail=True)` decorated method{basename}-{url_name}
By default the URLs created by `SimpleRouter` are appended with a trailing slash. @@ -160,12 +182,12 @@ This router is similar to `SimpleRouter` as above, but additionally includes a d [.format]GETautomatically generated root viewapi-root {prefix}/[.format]GETlist{basename}-list POSTcreate - {prefix}/{methodname}/[.format]GET, or as specified by `methods` argument`@list_route` decorated method{basename}-{methodname} + {prefix}/{url_path}/[.format]GET, or as specified by `methods` argument`@action(detail=False)` decorated method{basename}-{url_name} {prefix}/{lookup}/[.format]GETretrieve{basename}-detail PUTupdate PATCHpartial_update DELETEdestroy - {prefix}/{lookup}/{methodname}/[.format]GET, or as specified by `methods` argument`@detail_route` decorated method{basename}-{methodname} + {prefix}/{lookup}/{url_path}/[.format]GET, or as specified by `methods` argument`@action(detail=True)` decorated method{basename}-{url_name} As with `SimpleRouter` the trailing slashes on the URL routes can be removed by setting the `trailing_slash` argument to `False` when instantiating the router. @@ -174,7 +196,7 @@ As with `SimpleRouter` the trailing slashes on the URL routes can be removed by # Custom Routers -Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the your URLs for your API are structured. Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view. +Implementing a custom router isn't something you'd need to do very often, but it can be useful if you have specific requirements about how the URLs for your API are structured. Doing so allows you to encapsulate the URL structure in a reusable way that ensures you don't have to write your URL patterns explicitly for each new view. The simplest way to implement a custom router is to subclass one of the existing router classes. The `.routes` attribute is used to template the URL patterns that will be mapped to each viewset. The `.routes` attribute is a list of `Route` named tuples. @@ -192,18 +214,18 @@ The arguments to the `Route` named tuple are: * `{basename}` - The base to use for the URL names that are created. -**initkwargs**: A dictionary of any additional arguments that should be passed when instantiating the view. Note that the `suffix` argument is reserved for identifying the viewset type, used when generating the view name and breadcrumb links. +**initkwargs**: A dictionary of any additional arguments that should be passed when instantiating the view. Note that the `detail`, `basename`, and `suffix` arguments are reserved for viewset introspection and are also used by the browsable API to generate the view name and breadcrumb links. ## Customizing dynamic routes -You can also customize how the `@list_route` and `@detail_route` decorators are routed. -To route either or both of these decorators, include a `DynamicListRoute` and/or `DynamicDetailRoute` named tuple in the `.routes` list. +You can also customize how the `@action` decorator is routed. Include the `DynamicRoute` named tuple in the `.routes` list, setting the `detail` argument as appropriate for the list-based and detail-based routes. In addition to `detail`, the arguments to `DynamicRoute` are: -The arguments to `DynamicListRoute` and `DynamicDetailRoute` are: +**url**: A string representing the URL to be routed. May include the same format strings as `Route`, and additionally accepts the `{url_path}` format string. -**url**: A string representing the URL to be routed. May include the same format strings as `Route`, and additionally accepts the `{methodname}` and `{methodnamehyphen}` format strings. +**name**: The name of the URL as used in `reverse` calls. May include the following format strings: -**name**: The name of the URL as used in `reverse` calls. May include the following format strings: `{basename}`, `{methodname}` and `{methodnamehyphen}`. +* `{basename}` - The base to use for the URL names that are created. +* `{url_name}` - The `url_name` provided to the `@action`. **initkwargs**: A dictionary of any additional arguments that should be passed when instantiating the view. @@ -211,7 +233,7 @@ The arguments to `DynamicListRoute` and `DynamicDetailRoute` are: The following example will only route to the `list` and `retrieve` actions, and does not use the trailing slash convention. - from rest_framework.routers import Route, DynamicDetailRoute, SimpleRouter + from rest_framework.routers import Route, DynamicRoute, SimpleRouter class CustomReadOnlyRouter(SimpleRouter): """ @@ -219,22 +241,25 @@ The following example will only route to the `list` and `retrieve` actions, and """ routes = [ Route( - url=r'^{prefix}$', - mapping={'get': 'list'}, - name='{basename}-list', - initkwargs={'suffix': 'List'} + url=r'^{prefix}$', + mapping={'get': 'list'}, + name='{basename}-list', + detail=False, + initkwargs={'suffix': 'List'} ), Route( - url=r'^{prefix}/{lookup}$', + url=r'^{prefix}/{lookup}$', mapping={'get': 'retrieve'}, name='{basename}-detail', + detail=True, initkwargs={'suffix': 'Detail'} ), - DynamicDetailRoute( - url=r'^{prefix}/{lookup}/{methodnamehyphen}$', - name='{basename}-{methodnamehyphen}', - initkwargs={} - ) + DynamicRoute( + url=r'^{prefix}/{lookup}/{url_path}$', + name='{basename}-{url_name}', + detail=True, + initkwargs={} + ) ] Let's take a look at the routes our `CustomReadOnlyRouter` would generate for a simple viewset. @@ -249,8 +274,8 @@ Let's take a look at the routes our `CustomReadOnlyRouter` would generate for a serializer_class = UserSerializer lookup_field = 'username' - @detail_route() - def group_names(self, request): + @action(detail=True) + def group_names(self, request, pk=None): """ Returns a list of all the group names that the given user belongs to. @@ -263,7 +288,7 @@ Let's take a look at the routes our `CustomReadOnlyRouter` would generate for a router = CustomReadOnlyRouter() router.register('users', UserViewSet) - urlpatterns = router.urls + urlpatterns = router.urls The following mappings would be generated... @@ -271,7 +296,7 @@ The following mappings would be generated... URLHTTP MethodActionURL Name /usersGETlistuser-list /users/{username}GETretrieveuser-detail - /users/{username}/group-namesGETgroup_namesuser-group-names + /users/{username}/group_namesGETgroup_namesuser-group-names For another example of setting the `.routes` attribute, see the source code for the `SimpleRouter` class. @@ -280,7 +305,7 @@ For another example of setting the `.routes` attribute, see the source code for If you want to provide totally custom behavior, you can override `BaseRouter` and override the `get_urls(self)` method. The method should inspect the registered viewsets and return a list of URL patterns. The registered prefix, viewset and basename tuples may be inspected by accessing the `self.registry` attribute. -You may also want to override the `get_default_base_name(self, viewset)` method, or else always explicitly set the `base_name` argument when registering your viewsets with the router. +You may also want to override the `get_default_basename(self, viewset)` method, or else always explicitly set the `basename` argument when registering your viewsets with the router. # Third Party Packages @@ -303,13 +328,15 @@ The [wq.db package][wq.db] provides an advanced [ModelRouter][wq.db-router] clas The [`DRF-extensions` package][drf-extensions] provides [routers][drf-extensions-routers] for creating [nested viewsets][drf-extensions-nested-viewsets], [collection level controllers][drf-extensions-collection-level-controllers] with [customizable endpoint names][drf-extensions-customizable-endpoint-names]. -[cite]: http://guides.rubyonrails.org/routing.html +[cite]: https://guides.rubyonrails.org/routing.html [route-decorators]: viewsets.md#marking-extra-actions-for-routing [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers -[wq.db]: http://wq.io/wq.db -[wq.db-router]: http://wq.io/docs/router -[drf-extensions]: http://chibisov.github.io/drf-extensions/docs/ -[drf-extensions-routers]: http://chibisov.github.io/drf-extensions/docs/#routers -[drf-extensions-nested-viewsets]: http://chibisov.github.io/drf-extensions/docs/#nested-routes -[drf-extensions-collection-level-controllers]: http://chibisov.github.io/drf-extensions/docs/#collection-level-controllers -[drf-extensions-customizable-endpoint-names]: http://chibisov.github.io/drf-extensions/docs/#controller-endpoint-name +[wq.db]: https://wq.io/wq.db +[wq.db-router]: https://wq.io/docs/router +[drf-extensions]: https://chibisov.github.io/drf-extensions/docs/ +[drf-extensions-routers]: https://chibisov.github.io/drf-extensions/docs/#routers +[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 diff --git a/docs/api-guide/schemas.md b/docs/api-guide/schemas.md index 7da6190345..e33a2a6112 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,536 +13,208 @@ 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. -## Representing schemas internally - -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. - -[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`. - -Other schema formats such as [Open API][open-api] ("Swagger"), -[JSON HyperSchema][json-hyperschema], or [API Blueprint][api-blueprint] can -also be supported by implementing a custom renderer class. - -## 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. - ---- - -# Adding a schema - -You'll need to install the `coreapi` package in order to add schema support -for REST framework. +Django REST Framework provides support for automatic generation of +[OpenAPI][openapi] schemas. - pip install coreapi +## Generating an OpenAPI Schema -REST framework includes functionality for auto-generating a schema, -or allows you to specify one explicitly. There are a few different ways to -add a schema to your API, depending on exactly what you need. +### Install `pyyaml` -## The get_schema_view shortcut +You'll need to install `pyyaml`, so that you can render your generated schema +into the commonly used YAML-based OpenAPI format. -The simplest way to include a schema in your project is to use the -`get_schema_view()` function. + pip install pyyaml - schema_view = get_schema_view(title="Server Monitoring API") +### Generating a static schema with the `generateschema` management command - urlpatterns = [ - url('^$', schema_view), - ... - ] +If your schema is static, you can use the `generateschema` management command: -Once the view has been added, you'll be able to make API requests to retrieve -the auto-generated schema definition. +```bash +./manage.py generateschema > openapi-schema.yml +``` - $ http http://127.0.0.1:8000/ Accept:application/vnd.coreapi+json - HTTP/1.0 200 OK - Allow: GET, HEAD, OPTIONS - Content-Type: application/vnd.coreapi+json +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. - { - "_meta": { - "title": "Server Monitoring API" - }, - "_type": "document", - ... - } +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. -The arguments to `get_schema_view()` are: +### Generating a dynamic schema with `SchemaView` -#### `title` +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. -May be used to provide a descriptive title for the schema definition. +To route a `SchemaView`, use the `get_schema_view()` helper. -#### `url` +In `urls.py`: -May be used to pass a canonical URL for the schema. +```python +from rest_framework.schemas import get_schema_view - schema_view = get_schema_view( - title='Server Monitoring API', - url='https://www.example.org/api/' - ) +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 …", + version="1.0.0" + ), name='openapi-schema'), + # ... +] +``` -#### `renderer_classes` +#### `get_schema_view()` -May be used to pass the set of renderer classes that can be used to render the API root endpoint. +The `get_schema_view()` helper takes the following keyword arguments: - from rest_framework.renderers import CoreJSONRenderer - from my_custom_package import APIBlueprintRenderer +* `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/', - renderer_classes=[CoreJSONRenderer, APIBlueprintRenderer] - ) + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/' + ) -## Using an explicit schema view +* `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. -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. + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + urlconf='myproject.urls' + ) -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. +* `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: -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.CoreJSONRenderer]) - def schema_view(request): - schema = generator.get_schema(request) - return response.Response(schema) - -**urls.py:** - - urlpatterns = [ - url('/', schema_view), - ... - ] + schema_url_patterns = [ + url(r'^api/', include('myproject.api.urls')), + ] -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.CoreJSONRenderer]) - 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.CoreJSONRenderer]) - def schema_view(request): - return response.Response(schema) - -## Static schema file - -A final option is to write your API schema as a static file, using one -of the available formats, such as Core JSON or Open API. - -You could then either: - -* Write a schema definition as a static file, and [serve the static file directly][static-files]. -* Write a schema definition that is loaded using `Core API`, and then - rendered to one of many available formats, depending on the client request. - ---- + schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + patterns=schema_url_patterns, + ) -# Schemas as documentation +* `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. -One common usage of API schemas is to use them to build documentation pages. +## Customizing Schema Generation -The schema generation in REST framework uses docstrings to automatically -populate descriptions in the schema document. +You may customize schema generation at the level of the schema as a whole, or +on a per-view basis. -These descriptions will be based on: +### Schema Level Customization -* 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. +In order to customize the top-level schema sublass +`rest_framework.schemas.openapi.SchemaGenerator` and provide it as an argument +to the `generateschema` command or `get_schema_view()` helper function. -## Examples +#### SchemaGenerator -An `APIView`, with an explicit method docstring. +A class that walks a list of routed URL patterns, requests the schema for each +view and collates the resulting OpenAPI schema. - 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: Create a new user. - post: List all the users. - """ - 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 - ---- - -# Alternate schema formats - -In order to support an alternate schema format, you need to implement a custom renderer -class that handles converting a `Document` instance into a bytestring representation. - -If there is a Core API codec package that supports encoding into the format you -want to use then implementing the renderer class can be done by using the codec. - -## Example - -For example, the `openapi_codec` package provides support for encoding or decoding -to the Open API ("Swagger") format: - - from rest_framework import renderers - from openapi_codec import OpenAPICodec - - class SwaggerRenderer(renderers.BaseRenderer): - media_type = 'application/openapi+json' - format = 'swagger' - - def render(self, data, media_type=None, renderer_context=None): - codec = OpenAPICodec() - return codec.dump(data) - ---- - -# API Reference - -## SchemaGenerator - -A class that deals with introspecting your API views, which can be used to -generate a schema. - -Typically you'll instantiate `SchemaGenerator` with a single argument, like so: +Typically you'll instantiate `SchemaGenerator` with a `title` 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.CoreJSONRenderer]) - 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. +* `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_links(self, request) +##### get_schema(self, request) -Return a nested dictionary containing all the links that should be included in the API schema. +Returns a dictionary that represents the OpenAPI 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. - -### get_link(self, path, method, view) - -Returns a `coreapi.Link` instance corresponding to the given view. - -You can override this if you need to provide custom behaviors for particular views. - -### get_description(self, path, method, view) - -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, view) - -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, view): - -Return a list of `coreapi.Link()` instances. One for each path parameter in the URL. + generator = SchemaGenerator(title='Stock Prices API') + schema = generator.get_schema() -### get_serializer_fields(self, path, method, view) +The `request` argument is optional, and may be used if you want to apply +per-user permissions to the resulting schema generation. -Return a list of `coreapi.Link()` instances. One for each field in the serializer class used by the view. +This is a good point to override if you want to customize the generated +dictionary, for example to add custom +[specification extensions][openapi-specification-extensions]. -### get_pagination_fields(self, path, method, view +### Per-View Customization -Return a list of `coreapi.Link()` instances, as returned by the `get_schema_fields()` method on any pagination class used by the view. +By default, view introspection is performed by an `AutoSchema` instance +accessible via the `schema` attribute on `APIView`. This provides the +appropriate [Open API operation object][openapi-operation] for the view, +request method and path: -### get_filter_fields(self, path, method, view) + auto_schema = view.schema + operation = auto_schema.get_operation(...) -Return a list of `coreapi.Link()` instances, as returned by the `get_schema_fields()` method of any filter classes used by the view. +In compiling the schema, `SchemaGenerator` calls `view.schema.get_operation()` +for each view, allowed method, and path. --- -## 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. +**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.) -#### `title` +--- -A name for the API. +In order to customize the operation generation, you should provide an `AutoSchema` subclass, overriding `get_operation()` as you need: -#### `url` + from rest_framework.views import APIView + from rest_framework.schemas.openapi import AutoSchema -A canonical URL for the API. + class CustomSchema(AutoSchema): + def get_operation(...): + # Implement custom introspection here (or in other sub-methods) -#### `content` + class CustomView(APIView): + """APIView subclass with custom schema introspection.""" + schema = CustomSchema() -A dictionary, containing the `Link` objects that the schema contains. +This provides complete control over view introspection. -In order to provide more structure to the schema, the `content` dictionary -may be nested, typically to a second level. For example: +You may disable schema generation for a view by setting `schema` to `None`: - content={ - "bookings": { - "list": Link(...), - "create": Link(...), - ... - }, - "venues": { - "list": Link(...), - ... - }, + class CustomView(APIView): ... - } - -### 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 + schema = None # Will not appear in schema -Represents a single input parameter on a given API endpoint. +This also applies to extra actions for `ViewSet`s: -#### `name` + class CustomViewSet(viewsets.ModelViewSet): -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. + @action(detail=True, schema=None) + def extra_action(self, request, pk=None): + ... +If you wish to provide a base `AutoSchema` subclass to be used throughout your +project you may adjust `settings.DEFAULT_SCHEMA_CLASS` appropriately. -[cite]: https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api -[coreapi]: http://www.coreapi.org/ -[corejson]: http://www.coreapi.org/specification/encoding/#core-json-encoding -[open-api]: https://openapis.org/ -[json-hyperschema]: http://json-schema.org/latest/json-schema-hypermedia.html -[api-blueprint]: https://apiblueprint.org/ -[static-files]: https://docs.djangoproject.com/en/dev/howto/static-files/ -[named-arguments]: https://docs.djangoproject.com/en/dev/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 diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 290e32f4fa..4679b1ed16 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -1,4 +1,7 @@ -source: serializers.py +--- +source: + - serializers.py +--- # Serializers @@ -57,10 +60,10 @@ At this point we've translated the model instance into Python native datatypes. Deserialization is similar. First we parse a stream into Python native datatypes... - from django.utils.six import BytesIO + import io from rest_framework.parsers import JSONParser - stream = BytesIO(json) + stream = io.BytesIO(json) data = JSONParser().parse(stream) ...then we restore those native datatypes into a dictionary of validated data. @@ -73,7 +76,7 @@ Deserialization is similar. First we parse a stream into Python native datatypes ## Saving instances -If we want to be able to return complete object instances based on the validated data we need to implement one or both of the `.create()` and `update()` methods. For example: +If we want to be able to return complete object instances based on the validated data we need to implement one or both of the `.create()` and `.update()` methods. For example: class CommentSerializer(serializers.Serializer): email = serializers.EmailField() @@ -152,7 +155,7 @@ When deserializing data, you always need to call `is_valid()` before attempting serializer.is_valid() # False serializer.errors - # {'email': [u'Enter a valid e-mail address.'], 'created': [u'This field is required.']} + # {'email': ['Enter a valid e-mail address.'], 'created': ['This field is required.']} Each key in the dictionary will be the field name, and the values will be lists of strings of any error messages corresponding to that field. The `non_field_errors` key may also be present, and will list any general validation errors. The name of the `non_field_errors` key may be customized using the `NON_FIELD_ERRORS_KEY` REST framework setting. @@ -197,7 +200,7 @@ Your `validate_` methods should return the validated value or raise #### Object-level validation -To do any other validation that requires access to multiple fields, add a method called `.validate()` to your `Serializer` subclass. This method takes a single argument, which is a dictionary of field values. It should raise a `ValidationError` if necessary, or just return the validated values. For example: +To do any other validation that requires access to multiple fields, add a method called `.validate()` to your `Serializer` subclass. This method takes a single argument, which is a dictionary of field values. It should raise a `serializers.ValidationError` if necessary, or just return the validated values. For example: from rest_framework import serializers @@ -208,7 +211,7 @@ To do any other validation that requires access to multiple fields, add a method def validate(self, data): """ - Check that the start is before the stop. + Check that start is before finish. """ if data['start'] > data['finish']: raise serializers.ValidationError("finish must occur after start") @@ -253,7 +256,7 @@ When passing data to a serializer instance, the unmodified data will be made ava By default, serializers must be passed values for all required fields or they will raise validation errors. You can use the `partial` argument in order to allow partial updates. # Update `comment` with partial data - serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True) + serializer = CommentSerializer(comment, data={'content': 'foo bar'}, partial=True) ## Dealing with nested objects @@ -293,7 +296,7 @@ When dealing with nested representations that support deserializing the data, an serializer.is_valid() # False serializer.errors - # {'user': {'email': [u'Enter a valid e-mail address.']}, 'created': [u'This field is required.']} + # {'user': {'email': ['Enter a valid e-mail address.']}, 'created': ['This field is required.']} Similarly, the `.validated_data` property will include nested data structures. @@ -308,7 +311,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') @@ -325,7 +328,7 @@ For updates you'll want to think carefully about how to handle updates to relati * Ignore the data and leave the instance as it is. * Raise a validation error. -Here's an example for an `update()` method on our previous `UserSerializer` class. +Here's an example for an `.update()` method on our previous `UserSerializer` class. def update(self, instance, validated_data): profile_data = validated_data.pop('profile') @@ -352,7 +355,7 @@ Here's an example for an `update()` method on our previous `UserSerializer` clas Because the behavior of nested creates and updates can be ambiguous, and may require complex dependencies between related models, REST framework 3 requires you to always write these methods explicitly. The default `ModelSerializer` `.create()` and `.update()` methods do not include support for writable nested representations. -It is possible that a third party package, providing automatic support some kinds of automatic writable nested representations may be released alongside the 3.1 release. +There are however, third-party packages available such as [DRF Writable Nested][thirdparty-writable-nested] that support automatic writable nested representations. #### Handling saving related instances in model manager classes @@ -415,7 +418,7 @@ You can provide arbitrary additional context by passing a `context` argument whe serializer = AccountSerializer(account, context={'request': request}) serializer.data - # {'id': 6, 'owner': u'denvercoder9', 'created': datetime.datetime(2013, 2, 12, 09, 44, 56, 678870), 'details': 'http://example.com/accounts/6/details'} + # {'id': 6, 'owner': 'denvercoder9', 'created': datetime.datetime(2013, 2, 12, 09, 44, 56, 678870), 'details': 'http://example.com/accounts/6/details'} The context dictionary can be used within any serializer field logic, such as a custom `.to_representation()` method, by accessing the `self.context` attribute. @@ -438,7 +441,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 +470,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 +488,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. @@ -493,6 +496,8 @@ The names in the `fields` and `exclude` attributes will normally map to model fi Alternatively names in the `fields` options can map to properties or methods which take no arguments that exist on the model class. +Since version 3.3.0, it is **mandatory** to provide one of the attributes `fields` or `exclude`. + ## Specifying nested serialization The default `ModelSerializer` uses primary keys for relationships, but you can also easily generate nested representations using the `depth` option: @@ -500,7 +505,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. @@ -529,8 +534,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. @@ -558,7 +563,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): @@ -570,6 +575,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. @@ -578,16 +585,6 @@ Alternative representations include serializing using hyperlinks, serializing co For full details see the [serializer relations][relations] documentation. -## Inheritance of the 'Meta' class - -The inner `Meta` class on serializers is not inherited from parent classes by default. This is the same behavior as with Django's `Model` and `ModelForm` classes. If you want the `Meta` class to inherit from a parent class you must do so explicitly. For example: - - class AccountSerializer(MyBaseSerializer): - class Meta(MyBaseSerializer.Meta): - model = Account - -Typically we would recommend *not* using inheritance on inner Meta classes, but instead declaring all options explicitly. - ## Customizing field mappings The ModelSerializer class also exposes an API that you can override in order to alter how serializer fields are automatically determined when instantiating the serializer. @@ -632,7 +629,7 @@ The default implementation returns a serializer class based on the `serializer_f 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. @@ -676,7 +673,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 @@ -708,9 +705,9 @@ 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'} + 'url': {'view_name': 'accounts', 'lookup_field': 'account_name'}, 'users': {'lookup_field': 'username'} } @@ -730,7 +727,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'] --- @@ -832,9 +829,7 @@ Here's an example of how you might choose to implement multiple updates: # We need to identify elements in the list using their primary key, # so use a writable field here, rather than the default which would be read-only. id = serializers.IntegerField() - ... - id = serializers.IntegerField(required=False) class Meta: list_serializer_class = BookListSerializer @@ -892,10 +887,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: @@ -916,7 +911,7 @@ Or use it to serialize multiple instances: ##### 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 `ValidationError` if the supplied data is in an incorrect format. +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. Once you've implemented `.to_internal_value()`, the basic validation API will be available on the serializer, and you will be able to use `.is_valid()`, `.validated_data` and `.errors`. @@ -931,15 +926,15 @@ Here's a complete example of our previous `HighScoreSerializer`, that's been upd # Perform the data validation. if not score: - raise ValidationError({ + raise serializers.ValidationError({ 'score': 'This field is required.' }) if not player_name: - raise ValidationError({ + raise serializers.ValidationError({ 'player_name': 'This field is required.' }) if len(player_name) > 10: - raise ValidationError({ + raise serializers.ValidationError({ 'player_name': 'May not be more than 10 characters.' }) @@ -950,10 +945,10 @@ Here's a complete example of our previous `HighScoreSerializer`, that's been upd '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): @@ -970,10 +965,11 @@ The following class is an example of a generic serializer that can handle coerci 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__'): @@ -996,6 +992,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,7 +1000,7 @@ The following class is an example of a generic serializer that can handle coerci ## Overriding serialization and deserialization behavior -If you need to alter the serialization, deserialization or validation of a serializer class you can do so by overriding the `.to_representation()` or `.to_internal_value()` methods. +If you need to alter the serialization or deserialization behavior of a serializer class, you can do so by overriding the `.to_representation()` or `.to_internal_value()` methods. Some reasons this might be useful include... @@ -1013,18 +1010,60 @@ 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 to modify the representation style. For example: + + def to_representation(self, instance): + """Convert `username` to lowercase.""" + ret = super().to_representation(instance) + ret['username'] = ret['username'].lower() + return ret + #### ``.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. -If any of the validation fails, then the method should raise a `serializers.ValidationError(errors)`. Typically the `errors` argument here will be a dictionary mapping field names to error messages. +If any of the validation fails, then the method should raise a `serializers.ValidationError(errors)`. The `errors` argument should be a dictionary mapping field names (or `settings.NON_FIELD_ERRORS_KEY`) to a list of error messages. If you don't need to alter deserialization behavior and instead want to provide object-level validation, it's recommended that you instead override the [`.validate()`](#object-level-validation) method. The `data` argument passed to this method will normally be the value of `request.data`, so the datatype it provides will depend on the parser classes you have configured for your API. +## Serializer Inheritance + +Similar to Django forms, you can extend and reuse serializers through inheritance. This allows you to declare a common set of fields or methods on a parent class that can then be used in a number of serializers. For example, + + class MyBaseSerializer(Serializer): + my_field = serializers.CharField() + + def validate_my_field(self, value): + ... + + class MySerializer(MyBaseSerializer): + ... + +Like Django's `Model` and `ModelForm` classes, the inner `Meta` class on serializers does not implicitly inherit from it's parents' inner `Meta` classes. If you want the `Meta` class to inherit from a parent class you must do so explicitly. For example: + + class AccountSerializer(MyBaseSerializer): + class Meta(MyBaseSerializer.Meta): + model = Account + +Typically we would recommend *not* using inheritance on inner Meta classes, but instead declaring all options explicitly. + +Additionally, the following caveats apply to serializer inheritance: + +* Normal Python name resolution rules apply. If you have multiple base classes that declare a `Meta` inner class, only the first one will be used. This means the child’s `Meta`, if it exists, otherwise the `Meta` of the first parent, etc. +* It’s possible to declaratively remove a `Field` inherited from a parent class by setting the name to be `None` on the subclass. + + class MyBaseSerializer(ModelSerializer): + my_field = serializers.CharField() + + class MySerializer(MyBaseSerializer): + my_field = None + + However, you can only use this technique to opt out from a field defined declaratively by a parent class; it won’t prevent the `ModelSerializer` from generating a default field. To opt-out from default fields, see [Specifying which fields to include](#specifying-which-fields-to-include). + ## Dynamically modifying fields Once a serializer has been initialized, the dictionary of fields that are set on the serializer may be accessed using the `.fields` attribute. Accessing and modifying this attribute allows you to dynamically modify the serializer. @@ -1051,7 +1090,7 @@ For example, if you wanted to be able to set which fields should be used by a se if fields is not None: # Drop any fields that are not specified in the `fields` argument. allowed = set(fields) - existing = set(self.fields.keys()) + existing = set(self.fields) for field_name in existing - allowed: self.fields.pop(field_name) @@ -1060,12 +1099,12 @@ 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) + >>> print(UserSerializer(user)) {'id': 2, 'username': 'jonwatts', 'email': 'jon@example.com'} >>> - >>> print UserSerializer(user, fields=('id', 'email')) + >>> print(UserSerializer(user, fields=('id', 'email'))) {'id': 2, 'email': 'jon@example.com'} ## Customizing the default fields @@ -1076,8 +1115,6 @@ This API included the `.get_field()`, `.get_pk_field()` and other methods. Because the serializers have been fundamentally redesigned with 3.0 this API no longer exists. You can still modify the fields that get created but you'll need to refer to the source code, and be aware that if the changes you make are against private bits of API then they may be subject to change. -A new interface for controlling this behavior is currently planned for REST framework 3.1. - --- # Third party packages @@ -1112,15 +1149,39 @@ The [dynamic-rest][dynamic-rest] package extends the ModelSerializer and ModelVi The [drf-dynamic-fields][drf-dynamic-fields] package provides a mixin to dynamically limit the fields per serializer to a subset specified by an URL parameter. +## DRF FlexFields + +The [drf-flex-fields][drf-flex-fields] package extends the ModelSerializer and ModelViewSet to provide commonly used functionality for dynamically setting fields and expanding primitive fields to nested models, both from URL parameters and your serializer class definitions. + +## Serializer Extensions + +The [django-rest-framework-serializer-extensions][drf-serializer-extensions] +package provides a collection of tools to DRY up your serializers, by allowing +fields to be defined on a per-view/request basis. Fields can be whitelisted, +blacklisted and child serializers can be optionally expanded. + ## HTML JSON Forms The [html-json-forms][html-json-forms] package provides an algorithm and serializer for processing `
` submissions per the (inactive) [HTML JSON Form specification][json-form-spec]. The serializer facilitates processing of arbitrarily nested JSON structures within HTML. For example, `` will be interpreted as `{"items": [{"id": "5"}]}`. +## DRF-Base64 + +[DRF-Base64][drf-base64] provides a set of field and model serializers that handles the upload of base64-encoded files. + +## QueryFields + +[djangorestframework-queryfields][djangorestframework-queryfields] allows API clients to specify which fields will be sent in the response via inclusion/exclusion query parameters. + +## DRF Writable Nested + +The [drf-writable-nested][drf-writable-nested] package provides writable nested model serializer which allows to create/update models with nested related data. + [cite]: https://groups.google.com/d/topic/django-users/sVFaOfQi4wY/discussion [relations]: relations.md -[model-managers]: https://docs.djangoproject.com/en/dev/topics/db/managers/ -[encapsulation-blogpost]: http://www.dabapps.com/blog/django-models-and-encapsulation/ -[django-rest-marshmallow]: http://tomchristie.github.io/django-rest-marshmallow/ +[model-managers]: https://docs.djangoproject.com/en/stable/topics/db/managers/ +[encapsulation-blogpost]: https://www.dabapps.com/blog/django-models-and-encapsulation/ +[thirdparty-writable-nested]: serializers.md#drf-writable-nested +[django-rest-marshmallow]: https://marshmallow-code.github.io/django-rest-marshmallow/ [marshmallow]: https://marshmallow.readthedocs.io/en/latest/ [serpy]: https://github.com/clarkduvall/serpy [mongoengine]: https://github.com/umutbozkurt/django-rest-framework-mongoengine @@ -1129,5 +1190,10 @@ The [html-json-forms][html-json-forms] package provides an algorithm and seriali [django-hstore]: https://github.com/djangonauts/django-hstore [dynamic-rest]: https://github.com/AltSchool/dynamic-rest [html-json-forms]: https://github.com/wq/html-json-forms +[drf-flex-fields]: https://github.com/rsinger86/drf-flex-fields [json-form-spec]: https://www.w3.org/TR/html-json-forms/ [drf-dynamic-fields]: https://github.com/dbrgn/drf-dynamic-fields +[drf-base64]: https://bitbucket.org/levit_scs/drf_base64 +[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 diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 58ceeeeb41..d42000260b 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 @@ -26,7 +29,7 @@ you should use the `api_settings` object. For example. from rest_framework.settings import api_settings - print api_settings.DEFAULT_AUTHENTICATION_CLASSES + print(api_settings.DEFAULT_AUTHENTICATION_CLASSES) The `api_settings` object will check for any user-defined settings, and otherwise fall back to the default values. Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal. @@ -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 @@ -94,38 +97,31 @@ A content negotiation class, that determines how a renderer is selected for the Default: `'rest_framework.negotiation.DefaultContentNegotiation'` ---- - -## Generic view settings +#### DEFAULT_SCHEMA_CLASS -*The following settings control the behavior of the generic class-based views.* +A view inspector class that will be used for schema generation. -#### DEFAULT_PAGINATION_SERIALIZER_CLASS +Default: `'rest_framework.schemas.openapi.AutoSchema'` --- -**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. +## Generic view settings ---- +*The following settings control the behavior of the generic class-based views.* #### 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 ---- - -**This setting has been removed.** - -See the pagination documentation for further guidance on [setting the pagination style](pagination.md#modifying-the-pagination-style). +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. ---- +Default: `None` #### PAGE_SIZE @@ -133,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 is pending deprecation.** - -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`. @@ -196,6 +172,8 @@ Default: `'version'` #### UNAUTHENTICATED_USER The class that should be used to initialize `request.user` for unauthenticated requests. +(If removing authentication entirely, e.g. by removing `django.contrib.auth` from +`INSTALLED_APPS`, set `UNAUTHENTICATED_USER` to `None`.) Default: `django.contrib.auth.models.AnonymousUser` @@ -227,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' - ) + ] --- @@ -241,7 +219,7 @@ Default: If set, this maps the `'pk'` identifier in the URL conf onto the actual field name when generating a schema path parameter. Typically this will be `'id'`. This gives a more suitable representation as "primary key" is an implementation -detail, wheras "identifier" is a more general concept. +detail, whereas "identifier" is a more general concept. Default: `True` @@ -362,6 +340,14 @@ The default style is to return minified responses, in line with [Heroku's API de Default: `True` +#### STRICT_JSON + +When set to `True`, JSON rendering and parsing will only observe syntactically valid JSON, raising an exception for the extended float values (`nan`, `inf`, `-inf`) accepted by Python's `json` module. This is the recommended setting, as these values are not generally supported. e.g., neither Javascript's `JSON.Parse` nor PostgreSQL's JSON data type accept these values. + +When set to `False`, JSON rendering and parsing will be permissive. However, these values are still invalid and will need to be specially handled in your code. + +Default: `True` + #### COERCE_DECIMAL_TO_STRING When returning decimal objects in API representations that do not support a native decimal type, it is normally best to return the value as a string. This avoids the loss of precision that occurs with binary floating point implementations. @@ -382,10 +368,15 @@ A string representing the function that should be used when generating view name This should be a function with the following signature: - view_name(cls, suffix=None) + view_name(self) -* `cls`: The view class. Typically the name function would inspect the name of the class when generating a descriptive name, by accessing `cls.__name__`. -* `suffix`: The optional suffix used when differentiating individual views in a viewset. +* `self`: The view instance. Typically the name function would inspect the name of the class when generating a descriptive name, by accessing `self.__class__.__name__`. + +If the view instance inherits `ViewSet`, it may have been initialized with several optional arguments: + +* `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. Default: `'rest_framework.views.get_view_name'` @@ -397,11 +388,15 @@ This setting can be changed to support markup styles other than the default mark This should be a function with the following signature: - view_description(cls, html=False) + view_description(self, html=False) -* `cls`: The view class. Typically the description function would inspect the docstring of the class when generating a description, by accessing `cls.__doc__` +* `self`: The view instance. Typically the description function would inspect the docstring of the class when generating a description, by accessing `self.__class__.__doc__` * `html`: A boolean indicating if HTML output is required. `True` when used in the browsable API, and `False` when used in generating `OPTIONS` responses. +If the view instance inherits `ViewSet`, it may have been initialized with several optional arguments: + +* `description`: A description explicitly provided to the view in the viewset. Typically, this is set by extra viewset `action`s, and should be used as-is. + Default: `'rest_framework.views.get_view_description'` ## HTML Select Field cutoffs @@ -456,7 +451,7 @@ An integer of 0 or more, that may be used to specify the number of application p Default: `None` -[cite]: http://www.python.org/dev/peps/pep-0020/ -[rfc4627]: http://www.ietf.org/rfc/rfc4627.txt +[cite]: https://www.python.org/dev/peps/pep-0020/ +[rfc4627]: https://www.ietf.org/rfc/rfc4627.txt [heroku-minified-json]: https://github.com/interagent/http-api-design#keep-json-minified-in-all-responses -[strftime]: http://docs.python.org/2/library/time.html#time.strftime +[strftime]: https://docs.python.org/3/library/time.html#time.strftime diff --git a/docs/api-guide/status-codes.md b/docs/api-guide/status-codes.md index f6ec3598fc..a37ba15d45 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 @@ -6,7 +9,7 @@ source: status.py > > — [RFC 2324][rfc2324], Hyper Text Coffee Pot Control Protocol -Using bare status codes in your responses isn't recommended. REST framework includes a set of named constants that you can use to make more code more obvious and readable. +Using bare status codes in your responses isn't recommended. REST framework includes a set of named constants that you can use to make your code more obvious and readable. from rest_framework import status from rest_framework.response import Response @@ -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 @@ -118,6 +129,6 @@ The following helper functions are available for identifying the category of the is_client_error() # 4xx is_server_error() # 5xx -[rfc2324]: http://www.ietf.org/rfc/rfc2324.txt -[rfc2616]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html -[rfc6585]: http://tools.ietf.org/html/rfc6585 +[rfc2324]: https://www.ietf.org/rfc/rfc2324.txt +[rfc2616]: https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html +[rfc6585]: https://tools.ietf.org/html/rfc6585 diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md index 1f8c892339..dab0e264dc 100644 --- a/docs/api-guide/testing.md +++ b/docs/api-guide/testing.md @@ -1,4 +1,7 @@ -source: test.py +--- +source: + - test.py +--- # Testing @@ -82,7 +85,11 @@ For example, when forcibly authenticating using a token, you might do something user = User.objects.get(username='olivia') request = factory.get('/accounts/django-superstars/') - force_authenticate(request, user=user, token=user.token) + force_authenticate(request, user=user, token=user.auth_token) + +--- + +**Note**: `force_authenticate` directly sets `request.user` to the in-memory `user` instance. If you are re-using the same `user` instance across multiple tests that update the saved `user` state, you may need to call [`refresh_from_db()`][refresh_from_db_docs] between tests. --- @@ -115,7 +122,7 @@ Extends [Django's existing `Client` class][client]. ## Making requests -The `APIClient` class supports the same request interface as Django's standard `Client` class. This means the that standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available. For example: +The `APIClient` class supports the same request interface as Django's standard `Client` class. This means that the standard `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()` and `.options()` methods are all available. For example: from rest_framework.test import APIClient @@ -162,7 +169,7 @@ The `credentials` method is appropriate for testing APIs that require authentica #### .force_authenticate(user=None, token=None) -Sometimes you may want to bypass authentication, and simple force all requests by the test client to be automatically treated as authenticated. +Sometimes you may want to bypass authentication entirely and force all requests by the test client to be automatically treated as authenticated. This can be a useful shortcut if you're testing the API but don't want to have to construct valid authentication credentials in order to make test requests. @@ -187,17 +194,30 @@ As usual CSRF validation will only apply to any session authenticated views. Th # RequestsClient REST framework also includes a client for interacting with your application -using the popular Python library, `requests`. +using the popular Python library, `requests`. This may be useful if: + +* You are expecting to interface with the API primarily from another Python service, +and want to test the service at the same level as the client will see. +* You want to write tests in such a way that they can also be run against a staging or +live environment. (See "Live tests" below.) This exposes exactly the same interface as if you were using a requests session directly. + from rest_framework.test import RequestsClient + client = RequestsClient() response = client.get('http://testserver/users/') assert response.status_code == 200 Note that the requests client requires you to pass fully qualified URLs. +## RequestsClient and working with the database + +The `RequestsClient` class is useful if you want to write tests that solely interact with the service interface. This is a little stricter than using the standard Django test client, as it means that all interactions should be via the API. + +If you're using `RequestsClient` you'll want to ensure that test setup, and results assertions are performed as regular API calls, rather than interacting with the database models directly. For example, rather than checking that `Customer.objects.count() == 3` you would list the customers endpoint, and ensure that it contains three records. + ## Headers & Authentication Custom headers and authentication credentials can be provided in the same way @@ -222,12 +242,12 @@ For example... client = RequestsClient() # Obtain a CSRF token. - response = client.get('/homepage/') + response = client.get('http://testserver/homepage/') assert response.status_code == 200 csrftoken = response.cookies['csrftoken'] # Interact with the API. - response = client.post('/organisations/', json={ + response = client.post('http://testserver/organisations/', json={ 'name': 'MegaCorp', 'status': 'active' }, headers={'X-CSRFToken': csrftoken}) @@ -277,7 +297,7 @@ similar way as with `RequestsClient`. --- -# Test cases +# 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`. @@ -309,6 +329,32 @@ You can use any of REST framework's test case classes as you would for the regul --- +# URLPatternsTestCase + +REST framework also provides a test case class for isolating `urlpatterns` on a per-class basis. Note that this inherits from Django's `SimpleTestCase`, and will most likely need to be mixed with another test case class. + +## Example + + from django.urls import include, path, reverse + from rest_framework.test import APITestCase, URLPatternsTestCase + + + class AccountTests(APITestCase, URLPatternsTestCase): + urlpatterns = [ + path('api/', include('api.urls')), + ] + + def test_create_account(self): + """ + Ensure we can create a new account object. + """ + url = reverse('account-list') + response = self.client.get(url, format='json') + self.assertEqual(response.status_code, status.HTTP_200_OK) + self.assertEqual(len(response.data), 1) + +--- + # Testing responses ## Checking the response data @@ -356,14 +402,15 @@ 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]: http://jacobian.org/writing/django-apps-with-buildout/#s-create-a-test-wrapper -[client]: https://docs.djangoproject.com/en/dev/topics/testing/tools/#the-test-client -[requestfactory]: https://docs.djangoproject.com/en/dev/topics/testing/advanced/#django.test.client.RequestFactory +[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 diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index da4d5f7252..215c735bf4 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -1,4 +1,7 @@ -source: throttling.py +--- +source: + - throttling.py +--- # Throttling @@ -28,10 +31,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' @@ -48,7 +51,7 @@ using the `APIView` class-based views. from rest_framework.views import APIView class ExampleView(APIView): - throttle_classes = (UserRateThrottle,) + throttle_classes = [UserRateThrottle] def get(self, request, format=None): content = { @@ -68,13 +71,13 @@ Or, if you're using the `@api_view` decorator with function based views. ## How clients are identified -The `X-Forwarded-For` and `Remote-Addr` HTTP headers 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` header will be used. +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. -If you need to strictly identify unique client IP addresses, you'll need to first configure the number of application proxies that the API runs behind by setting the `NUM_PROXIES` setting. This setting should be an integer of zero or more. If set to non-zero then the client IP will be identified as being the last IP address in the `X-Forwarded-For` header, once any application proxy IP addresses have first been excluded. If set to zero, then the `Remote-Addr` header will always be used as the identifying IP address. +If you need to strictly identify unique client IP addresses, you'll need to first configure the number of application proxies that the API runs behind by setting the `NUM_PROXIES` setting. This setting should be an integer of zero or more. If set to non-zero then the client IP will be identified as being the last IP address in the `X-Forwarded-For` header, once any application proxy IP addresses have first been excluded. If set to zero, then the `REMOTE_ADDR` value will always be used as the identifying IP address. -It is important to understand that if you configure the `NUM_PROXIES` setting, then all clients behind a unique [NAT'd](http://en.wikipedia.org/wiki/Network_address_translation) gateway will be treated as a single client. +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 @@ -82,8 +85,10 @@ The throttle classes provided by REST framework use Django's cache backend. You If you need to use a cache other than `'default'`, you can do so by creating a custom throttle class and setting the `cache` attribute. For example: + from django.core.cache import caches + class CustomAnonRateThrottle(AnonRateThrottle): - cache = get_cache('alternate') + cache = caches['alternate'] 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. @@ -124,10 +129,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' @@ -159,9 +164,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' @@ -190,8 +195,8 @@ The following is an example of a rate throttle, that will randomly throttle 1 in def allow_request(self, request, view): return random.randint(1, 10) != 1 -[cite]: https://dev.twitter.com/docs/error-codes-responses +[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 -[cache-setting]: https://docs.djangoproject.com/en/dev/ref/settings/#caches -[cache-docs]: https://docs.djangoproject.com/en/dev/topics/cache/#setting-up-the-cache +[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 diff --git a/docs/api-guide/validators.md b/docs/api-guide/validators.md index 1af9f02a56..009cd2468d 100644 --- a/docs/api-guide/validators.md +++ b/docs/api-guide/validators.md @@ -1,4 +1,7 @@ -source: validators.py +--- +source: + - validators.py +--- # Validators @@ -20,7 +23,7 @@ With `ModelForm` the validation is performed partially on the form, and partiall * 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 a `Serializer` classes instead, then you need to define the validation rules explicitly. +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. #### Example @@ -84,7 +87,7 @@ It has two required arguments, and a single optional `messages` argument: The validator should be applied to *serializer classes*, like so: from rest_framework.validators import UniqueTogetherValidator - + class ExampleSerializer(serializers.Serializer): # ... class Meta: @@ -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,17 +152,15 @@ 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 it's default value to the `validated_data` in the serializer. +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. published = serializers.HiddenField(default=timezone.now) --- -**Note**: The `UniqueForValidation` classes always imposes 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. --- @@ -189,7 +190,6 @@ A default class that can be used to *only set a default argument during create o It takes a single argument, which is the default value or callable that should be used during create operations. created_at = serializers.DateTimeField( - read_only=True, default=serializers.CreateOnlyDefault(timezone.now) ) @@ -218,12 +218,12 @@ 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') - extra_kwargs = {'client': {'required': 'False'}} + fields = ['client', 'date', 'amount'] + extra_kwargs = {'client': {'required': False}} validators = [] # Remove a default "unique together" constraint. ## Updating nested serializers @@ -276,7 +276,7 @@ A validator may be any callable that raises a `serializers.ValidationError` on f You can specify custom field-level validation by adding `.validate_` methods to your `Serializer` subclass. This is documented in the -[Serializer docs](http://www.django-rest-framework.org/api-guide/serializers/#field-level-validation) +[Serializer docs](https://www.django-rest-framework.org/api-guide/serializers/#field-level-validation) ## Class-based @@ -291,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 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. -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. + requires_context = True - 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 + def __call__(self, value, serializer_field): + ... -[cite]: https://docs.djangoproject.com/en/dev/ref/validators/ +[cite]: https://docs.djangoproject.com/en/stable/ref/validators/ diff --git a/docs/api-guide/versioning.md b/docs/api-guide/versioning.md index 29672c96ea..6076b1ed2f 100644 --- a/docs/api-guide/versioning.md +++ b/docs/api-guide/versioning.md @@ -1,4 +1,7 @@ -source: versioning.py +--- +source: + - versioning.py +--- # Versioning @@ -37,7 +40,7 @@ The `reverse` function included by REST framework ties in with the versioning sc The above function will apply any URL transformations appropriate to the request version. For example: -* If `NamespacedVersioning` was being used, and the API version was 'v1', then the URL lookup used would be `'v1:bookings-list'`, which might resolve to a URL like `http://example.org/v1/bookings/`. +* If `NamespaceVersioning` was being used, and the API version was 'v1', then the URL lookup used would be `'v1:bookings-list'`, which might resolve to a URL like `http://example.org/v1/bookings/`. * If `QueryParameterVersioning` was being used, and the API version was `1.0`, then the returned URL might be something like `http://example.org/bookings/?version=1.0` #### Versioned APIs and hyperlinked serializers @@ -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. @@ -183,7 +186,7 @@ By default this implementation expects the hostname to match this simple regular Note that the first group is enclosed in brackets, indicating that this is the matched portion of the hostname. -The `HostNameVersioning` scheme can be awkward to use in debug mode as you will typically be accessing a raw IP address such as `127.0.0.1`. There are various online services which you to [access localhost with a custom subdomain][lvh] which you may find helpful in this case. +The `HostNameVersioning` scheme can be awkward to use in debug mode as you will typically be accessing a raw IP address such as `127.0.0.1`. There are various online tutorials on how to [access localhost with a custom subdomain][lvh] which you may find helpful in this case. Hostname based versioning can be particularly useful if you have requirements to route incoming requests to different servers based on the version, as you can configure different DNS records for different API versions. @@ -211,10 +214,10 @@ The following example uses a custom `X-API-Version` header to determine the requ If your versioning scheme is based on the request URL, you will also want to alter how versioned URLs are determined. In order to do so you should override the `.reverse()` method on the class. See the source code for examples. -[cite]: http://www.slideshare.net/evolve_conference/201308-fielding-evolve/31 -[roy-fielding-on-versioning]: http://www.infoq.com/articles/roy-fielding-on-versioning +[cite]: https://www.slideshare.net/evolve_conference/201308-fielding-evolve/31 +[roy-fielding-on-versioning]: https://www.infoq.com/articles/roy-fielding-on-versioning [klabnik-guidelines]: http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned [heroku-guidelines]: https://github.com/interagent/http-api-design/blob/master/en/foundations/require-versioning-in-the-accepts-header.md -[json-parameters]: http://tools.ietf.org/html/rfc4627#section-6 -[vendor-media-type]: http://en.wikipedia.org/wiki/Internet_media_type#Vendor_tree +[json-parameters]: https://tools.ietf.org/html/rfc4627#section-6 +[vendor-media-type]: https://en.wikipedia.org/wiki/Internet_media_type#Vendor_tree [lvh]: https://reinteractive.net/posts/199-developing-and-testing-rails-applications-with-subdomains diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index 55f6664e07..45226d57b5 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 @@ -23,6 +26,7 @@ For example: from rest_framework.views import APIView from rest_framework.response import Response from rest_framework import authentication, permissions + from django.contrib.auth.models import User class ListUsers(APIView): """ @@ -31,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): """ @@ -41,6 +45,13 @@ For example: usernames = [user.username for user in User.objects.all()] return Response(usernames) +--- + +**Note**: The full methods, attributes on, and relations between Django REST Framework's `APIView`, `GenericAPIView`, various `Mixins`, and `Viewsets` can be initially complex. In addition to the documentation here, the [Classy Django REST Framework][classy-drf] resource provides a browsable reference, with full methods and attributes, for each of Django REST Framework's class-based views. + +--- + + ## API policy attributes The following attributes control the pluggable aspects of API views. @@ -73,6 +84,8 @@ The following methods are used by REST framework to instantiate the various plug ### .get_content_negotiator(self) +### .get_exception_handler(self) + ## API policy implementation methods The following methods are called before dispatching to the handler method. @@ -127,7 +140,7 @@ REST framework also allows you to work with regular function based views. It pr ## @api_view() -**Signature:** `@api_view(http_method_names=['GET'], exclude_from_schema=False)` +**Signature:** `@api_view(http_method_names=['GET'])` 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: @@ -147,12 +160,6 @@ By default only `GET` methods will be accepted. Other methods will respond with return Response({"message": "Got some data!", "data": request.data}) return Response({"message": "Hello, world!"}) -You can also mark an API view as being omitted from any [auto-generated schema][schemas], -using the `exclude_from_schema` argument.: - - @api_view(['GET'], exclude_from_schema=True) - def api_docs(request): - ... ## API policy decorators @@ -181,8 +188,39 @@ The available decorators are: Each of these decorators takes a single argument which must be a list or tuple of classes. -[cite]: http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html + +## View schema decorator + +To override the default schema generation for function based views you may use +the `@schema` decorator. This must come *after* (below) the `@api_view` +decorator. For example: + + from rest_framework.decorators import api_view, schema + from rest_framework.schemas import AutoSchema + + class CustomAutoSchema(AutoSchema): + def get_link(self, path, method, base_url): + # override view introspection here... + + @api_view(['GET']) + @schema(CustomAutoSchema()) + def view(request): + return Response({"message": "Hello for today! See you tomorrow!"}) + +This decorator takes a single `AutoSchema` instance, an `AutoSchema` subclass +instance or `ManualSchema` instance as described in the [Schemas documentation][schemas]. +You may pass `None` in order to exclude the view from schema generation. + + @api_view(['GET']) + @schema(None) + def view(request): + return Response({"message": "Will not appear in schema!"}) + + +[cite]: https://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html [cite2]: http://www.boredomandlaziness.org/2012/05/djangos-cbvs-are-not-mistake-but.html [settings]: settings.md [throttling]: throttling.md [schemas]: schemas.md +[classy-drf]: http://www.cdrf.co + diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index e6df17f51d..cd765d3e68 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -1,4 +1,7 @@ -source: viewsets.py +--- +source: + - viewsets.py +--- # ViewSets @@ -51,7 +54,7 @@ Typically we wouldn't do this, but would instead register the viewset with a rou from rest_framework.routers import DefaultRouter router = DefaultRouter() - router.register(r'users', UserViewSet) + router.register(r'users', UserViewSet, basename='user') urlpatterns = router.urls Rather than writing your own viewsets, you'll often want to use the existing base classes that provide a default set of behavior. For example: @@ -70,9 +73,10 @@ There are two main advantages of using a `ViewSet` class over using a `View` cla Both of these come with a trade-off. Using regular views and URL confs is more explicit and gives you more control. ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout. -## Marking extra actions for routing -The default routers included with REST framework will provide routes for a standard set of create/retrieve/update/destroy style operations, as shown below: +## ViewSet actions + +The default routers included with REST framework will provide routes for a standard set of create/retrieve/update/destroy style actions, as shown below: class UserViewSet(viewsets.ViewSet): """ @@ -101,16 +105,38 @@ The default routers included with REST framework will provide routes for a stand def destroy(self, request, pk=None): pass -If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@detail_route` or `@list_route` decorators. +## Introspecting ViewSet actions + +During dispatch, the following attributes are available on the `ViewSet`. + +* `basename` - the base to use for the URL names that are created. +* `action` - the name of the current action (e.g., `list`, `create`). +* `detail` - boolean indicating if the current action is configured for a list or detail view. +* `suffix` - the display suffix for the viewset type - mirrors the `detail` attribute. +* `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: -The `@detail_route` decorator contains `pk` in its URL pattern and is intended for methods which require a single instance. The `@list_route` decorator is intended for methods which operate on a list of objects. + def get_permissions(self): + """ + Instantiates and returns the list of permissions that this view requires. + """ + if self.action == 'list': + permission_classes = [IsAuthenticated] + else: + permission_classes = [IsAdmin] + return [permission() for permission in permission_classes] + +## Marking extra actions for routing -For example: +If you have ad-hoc methods that should be routable, you can mark them as such with the `@action` decorator. Like regular actions, extra actions may be intended for either a single object, or an entire collection. To indicate this, set the `detail` argument to `True` or `False`. The router will configure its URL patterns accordingly. e.g., the `DefaultRouter` will configure detail actions to contain `pk` in their URL patterns. + +A more complete example of extra actions: from django.contrib.auth.models import User - from rest_framework import status - from rest_framework import viewsets - from rest_framework.decorators import detail_route, list_route + from rest_framework import status, viewsets + from rest_framework.decorators import action from rest_framework.response import Response from myapp.serializers import UserSerializer, PasswordSerializer @@ -121,7 +147,7 @@ For example: queryset = User.objects.all() serializer_class = UserSerializer - @detail_route(methods=['post']) + @action(detail=True, methods=['post']) def set_password(self, request, pk=None): user = self.get_object() serializer = PasswordSerializer(data=request.data) @@ -133,9 +159,9 @@ For example: return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST) - @list_route() + @action(detail=False) def recent_users(self, request): - recent_users = User.objects.all().order('-last_login') + recent_users = User.objects.all().order_by('-last_login') page = self.paginate_queryset(recent_users) if page is not None: @@ -145,20 +171,60 @@ For example: serializer = self.get_serializer(recent_users, many=True) return Response(serializer.data) -The decorators can additionally take extra arguments that will be set for the routed view only. For example... +The decorator can additionally take extra arguments that will be set for the routed view only. For example: - @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf]) + @action(detail=True, methods=['post'], permission_classes=[IsAdminOrIsSelf]) def set_password(self, request, pk=None): ... -These decorators will route `GET` requests by default, but may also accept other HTTP methods, by using the `methods` argument. For example: +The `action` decorator will route `GET` requests by default, but may also accept other HTTP methods by setting the `methods` argument. For example: - @detail_route(methods=['post', 'delete']) + @action(detail=True, methods=['post', 'delete']) 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/$` +To view all extra actions, call the `.get_extra_actions()` method. + +### Routing additional HTTP methods for extra actions + +Extra actions can map additional HTTP methods to separate `ViewSet` methods. For example, the above password set/unset methods could be consolidated into a single route. Note that additional mappings do not accept arguments. + +```python + @action(detail=True, methods=['put'], name='Change Password') + def password(self, request, pk=None): + """Update the user's password.""" + ... + + @password.mapping.delete + def delete_password(self, request, pk=None): + """Delete the user's password.""" + ... +``` + +## Reversing action URLs + +If you need to get the URL of an action, use the `.reverse_action()` method. This is a convenience wrapper for `reverse()`, automatically passing the view's `request` object and prepending the `url_name` with the `.basename` attribute. + +Note that the `basename` is provided by the router during `ViewSet` registration. If you are not using a router, then you must provide the `basename` argument to the `.as_view()` method. + +Using the example from the previous section: + +```python +>>> view.reverse_action('set-password', args=['1']) +'http://localhost:8000/api/users/1/set_password' +``` + +Alternatively, you can use the `url_name` attribute set by the `@action` decorator. + +```python +>>> view.reverse_action(view.set_password.url_name, args=['1']) +'http://localhost:8000/api/users/1/set_password' +``` + +The `url_name` argument for `.reverse_action()` should match the same argument to the `@action` decorator. Additionally, this method can be used to reverse the default actions, such as `list` and `create`. + --- # API Reference @@ -206,7 +272,7 @@ Note that you can use any of the standard attributes or method overrides provide def get_queryset(self): return self.request.user.accounts.all() -Note however that upon removal of the `queryset` property from your `ViewSet`, any associated [router][routers] will be unable to derive the base_name of your Model automatically, and so you will have to specify the `base_name` kwarg as part of your [router registration][routers]. +Note however that upon removal of the `queryset` property from your `ViewSet`, any associated [router][routers] will be unable to derive the basename of your Model automatically, and so you will have to specify the `basename` kwarg as part of your [router registration][routers]. Also note that although this class provides the complete set of create/list/retrieve/update/destroy actions by default, you can restrict the available operations by using the standard permission classes. @@ -235,6 +301,8 @@ You may need to provide custom `ViewSet` classes that do not have the full set o To create a base viewset class that provides `create`, `list` and `retrieve` operations, inherit from `GenericViewSet`, and mixin the required actions: + from rest_framework import mixins + class CreateListRetrieveViewSet(mixins.CreateModelMixin, mixins.ListModelMixin, mixins.RetrieveModelMixin, @@ -249,5 +317,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]: http://guides.rubyonrails.org/routing.html +[cite]: https://guides.rubyonrails.org/routing.html [routers]: routers.md diff --git a/docs/topics/3.0-announcement.md b/docs/community/3.0-announcement.md similarity index 95% rename from docs/topics/3.0-announcement.md rename to docs/community/3.0-announcement.md index e6cbf72385..b9461defe9 100644 --- a/docs/topics/3.0-announcement.md +++ b/docs/community/3.0-announcement.md @@ -32,7 +32,7 @@ Significant new functionality continues to be planned for the 3.1 and 3.2 releas #### REST framework: Under the hood. -This talk from the [Django: Under the Hood](http://www.djangounderthehood.com/) event in Amsterdam, Nov 2014, gives some good background context on the design decisions behind 3.0. +This talk from the [Django: Under the Hood](https://www.djangounderthehood.com/) event in Amsterdam, Nov 2014, gives some good background context on the design decisions behind 3.0. @@ -119,7 +119,7 @@ This would now be split out into two separate methods. instance.save() return instance - def create(self, validated_data): + def create(self, validated_data): return Snippet.objects.create(**validated_data) Note that these methods should return the newly created object instance. @@ -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,9 +327,9 @@ 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} + 'is_admin': {'write_only': True} } Alternatively, specify the field explicitly on the serializer class: @@ -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,12 +384,12 @@ 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. >>> serializer = InvitationSerializer() - >>> print repr(serializer) + >>> print(repr(serializer)) InvitationSerializer(): to_email = EmailField(max_length=75) message = CharField(max_length=1000) @@ -454,7 +454,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: @@ -462,7 +462,7 @@ 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. @@ -493,8 +493,8 @@ 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 @@ -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__'): @@ -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. @@ -870,7 +870,7 @@ The `COMPACT_JSON` setting has been added, and can be used to revert this behavi #### File fields as URLs -The `FileField` and `ImageField` classes are now represented as URLs by default. You should ensure you set Django's [standard `MEDIA_URL` setting](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-MEDIA_URL) appropriately, and ensure your application [serves the uploaded files](https://docs.djangoproject.com/en/dev/howto/static-files/#serving-uploaded-files-in-development). +The `FileField` and `ImageField` classes are now represented as URLs by default. You should ensure you set Django's [standard `MEDIA_URL` setting](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-MEDIA_URL) appropriately, and ensure your application [serves the uploaded files](https://docs.djangoproject.com/en/stable/howto/static-files/#serving-uploaded-files-in-development). You can revert this behavior, and display filenames in the representation by using the `UPLOADED_FILES_USE_URL` settings key: @@ -894,11 +894,11 @@ If the request is omitted from the context, the returned URLs will be of the for The custom `X-Throttle-Wait-Second` header has now been dropped in favor of the standard `Retry-After` header. You can revert this behavior if needed by writing a custom exception handler for your application. -#### Date and time objects as ISO-8859-1 strings in serializer data. +#### Date and time objects as ISO-8601 strings in serializer data. Date and Time objects are now coerced to strings by default in the serializer output. Previously they were returned as `Date`, `Time` and `DateTime` objects, and later coerced to strings by the renderer. -You can modify this behavior globally by settings the existing `DATE_FORMAT`, `DATETIME_FORMAT` and `TIME_FORMAT` settings keys. Setting these values to `None` instead of their default value of `'iso-8859-1'` will result in native objects being returned in serializer data. +You can modify this behavior globally by settings the existing `DATE_FORMAT`, `DATETIME_FORMAT` and `TIME_FORMAT` settings keys. Setting these values to `None` instead of their default value of `'iso-8601'` will result in native objects being returned in serializer data. REST_FRAMEWORK = { # Return native `Date` and `Time` objects in `serializer.data` @@ -957,9 +957,9 @@ The 3.1 release is planned to address improvements in the following components: The 3.2 release is planned to introduce an alternative admin-style interface to the browsable API. -You can follow development on the GitHub site, where we use [milestones to indicate planning timescales](https://github.com/tomchristie/django-rest-framework/milestones). +You can follow development on the GitHub site, where we use [milestones to indicate planning timescales](https://github.com/encode/django-rest-framework/milestones). -[kickstarter]: http://kickstarter.com/projects/tomchristie/django-rest-framework-3 -[sponsors]: http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors -[mixins.py]: https://github.com/tomchristie/django-rest-framework/blob/master/rest_framework/mixins.py -[django-localization]: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#localization-how-to-create-language-files +[kickstarter]: https://www.kickstarter.com/projects/tomchristie/django-rest-framework-3 +[sponsors]: https://www.django-rest-framework.org/community/kickstarter-announcement/#sponsors +[mixins.py]: https://github.com/encode/django-rest-framework/blob/master/rest_framework/mixins.py +[django-localization]: https://docs.djangoproject.com/en/stable/topics/i18n/translation/#localization-how-to-create-language-files diff --git a/docs/topics/3.1-announcement.md b/docs/community/3.1-announcement.md similarity index 89% rename from docs/topics/3.1-announcement.md rename to docs/community/3.1-announcement.md index 9eb93fcd74..641f313d06 100644 --- a/docs/topics/3.1-announcement.md +++ b/docs/community/3.1-announcement.md @@ -30,7 +30,7 @@ Note that as a result of this work a number of settings keys and generic view at Until now, there has only been a single built-in pagination style in REST framework. We now have page, limit/offset and cursor based schemes included by default. -The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. It also allows for both forward and reverse cursor pagination. Much credit goes to David Cramer for [this blog post](http://cramer.io/2011/03/08/building-cursors-for-the-disqus-api) on the subject. +The cursor based pagination scheme is particularly smart, and is a better approach for clients iterating through large or frequently changing result sets. The scheme supports paging against non-unique indexes, by using both cursor and limit/offset information. It also allows for both forward and reverse cursor pagination. Much credit goes to David Cramer for [this blog post](https://cra.mr/2011/03/08/building-cursors-for-the-disqus-api) on the subject. #### Pagination controls in the browsable API. @@ -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: @@ -114,7 +114,7 @@ Note that the structure of the error responses is still the same. We still have We include built-in translations both for standard exception cases, and for serializer validation errors. -The full list of supported languages can be found on our [Transifex project page](https://www.transifex.com/projects/p/django-rest-framework/). +The full list of supported languages can be found on our [Transifex project page](https://www.transifex.com/django-rest-framework-1/django-rest-framework/). If you only wish to support a subset of the supported languages, use Django's standard `LANGUAGES` setting: @@ -123,7 +123,7 @@ If you only wish to support a subset of the supported languages, use Django's st ('en', _('English')), ] -For more details, see the [internationalization documentation](internationalization.md). +For more details, see the [internationalization documentation][internationalization]. Many thanks to [Craig Blaszczyk](https://github.com/jakul) for helping push this through. @@ -153,16 +153,16 @@ For more information, see the documentation on [customizing field mappings][cust We've now moved a number of packages out of the core of REST framework, and into separately installable packages. If you're currently using these you don't need to worry, you simply need to `pip install` the new packages, and change any import paths. -We're making this change in order to help distribute the maintainance workload, and keep better focus of the core essentials of the framework. +We're making this change in order to help distribute the maintenance workload, and keep better focus of the core essentials of the framework. -The change also means we can be more flexible with which external packages we recommend. For example, the excellently maintained [Django OAuth toolkit](https://github.com/evonove/django-oauth-toolkit) has now been promoted as our recommended option for integrating OAuth support. +The change also means we can be more flexible with which external packages we recommend. For example, the excellently maintained [Django OAuth toolkit](https://github.com/jazzband/django-oauth-toolkit) has now been promoted as our recommended option for integrating OAuth support. The following packages are now moved out of core and should be separately installed: -* OAuth - [djangorestframework-oauth](http://jpadilla.github.io/django-rest-framework-oauth/) -* XML - [djangorestframework-xml](http://jpadilla.github.io/django-rest-framework-xml) -* YAML - [djangorestframework-yaml](http://jpadilla.github.io/django-rest-framework-yaml) -* JSONP - [djangorestframework-jsonp](http://jpadilla.github.io/django-rest-framework-jsonp) +* OAuth - [djangorestframework-oauth](https://jpadilla.github.io/django-rest-framework-oauth/) +* XML - [djangorestframework-xml](https://jpadilla.github.io/django-rest-framework-xml/) +* YAML - [djangorestframework-yaml](https://jpadilla.github.io/django-rest-framework-yaml/) +* JSONP - [djangorestframework-jsonp](https://jpadilla.github.io/django-rest-framework-jsonp/) It's worth reiterating that this change in policy shouldn't mean any work in your codebase other than adding a new requirement and modifying some import paths. For example to install XML rendering, you would now do: @@ -205,5 +205,5 @@ This will either be made as a single 3.2 release, or split across two separate r [custom-exception-handler]: ../api-guide/exceptions.md#custom-exception-handling [pagination]: ../api-guide/pagination.md [versioning]: ../api-guide/versioning.md -[internationalization]: internationalization.md +[internationalization]: ../topics/internationalization.md [customizing-field-mappings]: ../api-guide/serializers.md#customizing-field-mappings diff --git a/docs/community/3.10-announcement.md b/docs/community/3.10-announcement.md new file mode 100644 index 0000000000..19748aa40d --- /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 0000000000..83dd636d19 --- /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/topics/3.2-announcement.md b/docs/community/3.2-announcement.md similarity index 93% rename from docs/topics/3.2-announcement.md rename to docs/community/3.2-announcement.md index dc439f1105..a66ad5d292 100644 --- a/docs/topics/3.2-announcement.md +++ b/docs/community/3.2-announcement.md @@ -8,9 +8,9 @@ This interface is intended to act as a more user-friendly interface to the API. We've also fixed a huge number of issues, and made numerous cleanups and improvements. -Over the course of the 3.1.x series we've [resolved nearly 600 tickets](https://github.com/tomchristie/django-rest-framework/issues?utf8=%E2%9C%93&q=closed%3A%3E2015-03-05) on our GitHub issue tracker. This means we're currently running at a rate of **closing around 100 issues or pull requests per month**. +Over the course of the 3.1.x series we've [resolved nearly 600 tickets](https://github.com/encode/django-rest-framework/issues?utf8=%E2%9C%93&q=closed%3A%3E2015-03-05) on our GitHub issue tracker. This means we're currently running at a rate of **closing around 100 issues or pull requests per month**. -None of this would have been possible without the support of our wonderful Kickstarter backers. If you're looking for a job in Django development we'd strongly recommend taking [a look through our sponsors](http://www.django-rest-framework.org/topics/kickstarter-announcement/#sponsors) and finding out who's hiring. +None of this would have been possible without the support of our wonderful Kickstarter backers. If you're looking for a job in Django development we'd strongly recommend taking [a look through our sponsors](https://www.django-rest-framework.org/community/kickstarter-announcement/#sponsors) and finding out who's hiring. ## AdminRenderer @@ -83,7 +83,7 @@ When using `allow_null` with `ListField` or a nested `many=True` serializer the For example, take the following field: - NestedSerializer(many=True, allow_null=True) + NestedSerializer(many=True, allow_null=True) Previously the validation behavior would be: @@ -110,4 +110,4 @@ This release is planned to include: * Improvements and public API for our templated HTML forms and fields. * Nested object and list support in HTML forms. -Thanks once again to all our sponsors and supporters. \ No newline at end of file +Thanks once again to all our sponsors and supporters. diff --git a/docs/topics/3.3-announcement.md b/docs/community/3.3-announcement.md similarity index 89% rename from docs/topics/3.3-announcement.md rename to docs/community/3.3-announcement.md index d1a8f4da0b..5dcbe3b3b5 100644 --- a/docs/topics/3.3-announcement.md +++ b/docs/community/3.3-announcement.md @@ -37,8 +37,8 @@ This brings our supported versions into line with Django's [currently supported The AJAX based support for the browsable API means that there are a number of internal cleanups in the `request` class. For the vast majority of developers this should largely remain transparent: * 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](browser-enhancements.md#url-based-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](browser-enhancements.md#http-header-based-method-overriding). +* 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 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. @@ -52,7 +52,9 @@ The following pagination view attributes and settings have been moved into attri The `ModelSerializer` and `HyperlinkedModelSerializer` classes should now include either a `fields` or `exclude` option, although the `fields = '__all__'` shortcut may be used. Failing to include either of these two options is currently pending deprecation, and will be removed entirely in the 3.5 release. This behavior brings `ModelSerializer` more closely in line with Django's `ModelForm` behavior. -[forms-api]: html-and-forms.md -[ajax-form]: https://github.com/tomchristie/ajax-form -[jsonfield]: ../../api-guide/fields#jsonfield -[django-supported-versions]: https://www.djangoproject.com/download/#supported-versions \ No newline at end of file +[forms-api]: ../topics/html-and-forms.md +[ajax-form]: https://github.com/encode/ajax-form +[jsonfield]: ../api-guide/fields#jsonfield +[accept-headers]: ../topics/browser-enhancements.md#url-based-accept-headers +[method-override]: ../topics/browser-enhancements.md#http-header-based-method-overriding +[django-supported-versions]: https://www.djangoproject.com/download/#supported-versions diff --git a/docs/topics/3.4-announcement.md b/docs/community/3.4-announcement.md similarity index 85% rename from docs/topics/3.4-announcement.md rename to docs/community/3.4-announcement.md index 69343c75e1..67192ecbb2 100644 --- a/docs/topics/3.4-announcement.md +++ b/docs/community/3.4-announcement.md @@ -36,13 +36,13 @@ Right now we're over 60% of the way towards achieving that. *Every single sign-up makes a significant impact.*
-*Many thanks to all our [awesome sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), and [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf).* +*Many thanks to all our [awesome sponsors][sponsors], and in particular to our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), and [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf).* --- @@ -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] | Currrently 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. --- @@ -178,17 +178,17 @@ The full set of itemized release notes [are available here][release-notes]. [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors [moss]: mozilla-grant.md [funding]: funding.md -[core-api]: http://www.coreapi.org/ +[core-api]: https://www.coreapi.org/ [command-line-client]: api-clients#command-line-client [client-library]: api-clients#python-client-library -[core-json]: http://www.coreapi.org/specification/encoding/#core-json-encoding +[core-json]: https://www.coreapi.org/specification/encoding/#core-json-encoding [swagger]: https://openapis.org/specification -[hyperschema]: http://json-schema.org/latest/json-schema-hypermedia.html +[hyperschema]: https://json-schema.org/latest/json-schema-hypermedia.html [api-blueprint]: https://apiblueprint.org/ -[tut-7]: ../../tutorial/7-schemas-and-client-libraries/ -[schema-generation]: ../../api-guide/schemas/ -[api-clients]: api-clients.md -[milestone]: https://github.com/tomchristie/django-rest-framework/milestone/35 +[tut-7]: ../tutorial/7-schemas-and-client-libraries/ +[schema-generation]: ../api-guide/schemas/ +[api-clients]: ../topics/api-clients.md +[milestone]: https://github.com/encode/django-rest-framework/milestone/35 [release-notes]: release-notes#34 -[metadata]: ../../api-guide/metadata/#custom-metadata-classes -[gh3751]: https://github.com/tomchristie/django-rest-framework/issues/3751 +[metadata]: ../api-guide/metadata/#custom-metadata-classes +[gh3751]: https://github.com/encode/django-rest-framework/issues/3751 diff --git a/docs/topics/3.5-announcement.md b/docs/community/3.5-announcement.md similarity index 90% rename from docs/topics/3.5-announcement.md rename to docs/community/3.5-announcement.md index ea50b24189..cce2dd0501 100644 --- a/docs/topics/3.5-announcement.md +++ b/docs/community/3.5-announcement.md @@ -32,14 +32,14 @@ we strongly encourage you to invest in its continued development by **[signing up for a paid plan][funding]**.
-*Many thanks to all our [sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), and [Machinalis](http://www.machinalis.com/#services).* +*Many thanks to all our [sponsors][sponsors], and in particular to our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), and [Machinalis](https://www.machinalis.com/#services).* --- @@ -256,11 +256,11 @@ in version 3.3 and raised a deprecation warning in 3.4. Its usage is now mandato [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors [funding]: funding.md -[uploads]: http://core-api.github.io/python-client/api-guide/utils/#file -[downloads]: http://core-api.github.io/python-client/api-guide/codecs/#downloadcodec +[uploads]: https://core-api.github.io/python-client/api-guide/utils/#file +[downloads]: https://core-api.github.io/python-client/api-guide/codecs/#downloadcodec [schema-generation-api]: ../api-guide/schemas/#schemagenerator [schema-docs]: ../api-guide/schemas/#schemas-as-documentation [schema-view]: ../api-guide/schemas/#the-get_schema_view-shortcut -[django-rest-raml]: https://github.com/tomchristie/django-rest-raml +[django-rest-raml]: https://github.com/encode/django-rest-raml [raml-image]: ../img/raml.png [raml-codec]: https://github.com/core-api/python-raml-codec diff --git a/docs/community/3.6-announcement.md b/docs/community/3.6-announcement.md new file mode 100644 index 0000000000..c41ad8ecbd --- /dev/null +++ b/docs/community/3.6-announcement.md @@ -0,0 +1,199 @@ + + +# Django REST framework 3.6 + +The 3.6 release adds two major new features to REST framework. + +1. Built-in interactive API documentation support. +2. A new JavaScript client library. + +![API Documentation](/img/api-docs.gif) + +*Above: The interactive API documentation.* + +--- + +## Funding + +The 3.6 release would not have been possible without our [backing from Mozilla](mozilla-grant.md) to the project, and our [collaborative funding model][funding]. + +If you use REST framework commercially and would like to see this work continue, +we strongly encourage you to invest in its continued development by +**[signing up for a paid plan][funding]**. + + +
+ +*Many thanks to all our [sponsors][sponsors], and in particular to our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://machinalis.com/), [Rollbar](https://rollbar.com), and [MicroPyramid](https://micropyramid.com/django-rest-framework-development-services/).* + +--- + +## Interactive API documentation + +REST framework's new API documentation supports a number of features: + +* Live API interaction. +* Support for various authentication schemes. +* Code snippets for the Python, JavaScript, and Command Line clients. + +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. + +To install the API documentation, you'll need to include it in your projects URLconf: + + from rest_framework.documentation import include_docs_urls + + API_TITLE = 'API title' + API_DESCRIPTION = '...' + + urlpatterns = [ + ... + url(r'^docs/', include_docs_urls(title=API_TITLE, description=API_DESCRIPTION)) + ] + +Once installed you should see something a little like this: + +![API Documentation](/img/api-docs.png) + +We'll likely be making further refinements to the API documentation over the +coming weeks. Keep in mind that this is a new feature, and please do give +us feedback if you run into any issues or limitations. + +For more information on documenting your API endpoints see the ["Documenting your API"][api-docs] section. + +--- + +## JavaScript client library + +The JavaScript client library allows you to load an API schema, and then interact +with that API at an application layer interface, rather than constructing fetch +requests explicitly. + +Here's a brief example that demonstrates: + +* Loading the client library and schema. +* Instantiating an authenticated client. +* Making an API request using the client. + +**index.html** + + + + + + + + + +The JavaScript client library supports various authentication schemes, and can be +used by your project itself, or as an external client interacting with your API. + +The client is not limited to usage with REST framework APIs, although it does +currently only support loading CoreJSON API schemas. Support for Swagger and +other API schemas is planned. + +For more details see the [JavaScript client library documentation][js-docs]. + +## Authentication classes for the Python client library + +Previous authentication support in the Python client library was limited to +allowing users to provide explicit header values. + +We now have better support for handling the details of authentication, with +the introduction of the `BasicAuthentication`, `TokenAuthentication`, and +`SessionAuthentication` schemes. + +You can include the authentication scheme when instantiating a new client. + + auth = coreapi.auth.TokenAuthentication(scheme='JWT', token='xxx-xxx-xxx') + client = coreapi.Client(auth=auth) + +For more information see the [Python client library documentation][py-docs]. + +--- + +## Deprecations + +### Updating coreapi + +If you're using REST framework's schema generation, or want to use the API docs, +then you'll need to update to the latest version of coreapi. (2.3.0) + +### Generating schemas from Router + +The 3.5 "pending deprecation" of router arguments for generating a schema view, such as `schema_title`, `schema_url` and `schema_renderers`, have now been escalated to a +"deprecated" warning. + +Instead of using `DefaultRouter(schema_title='Example API')`, you should use the `get_schema_view()` function, and include the view explicitly in your URL conf. + +### DjangoFilterBackend + +The 3.5 "pending deprecation" warning of the built-in `DjangoFilterBackend` has now +been escalated to a "deprecated" warning. + +You should change your imports and REST framework filter settings as follows: + +* `rest_framework.filters.DjangoFilterBackend` becomes `django_filters.rest_framework.DjangoFilterBackend`. +* `rest_framework.filters.FilterSet` becomes `django_filters.rest_framework.FilterSet`. + +--- + +## What's next + +There are likely to be a number of refinements to the API documentation and +JavaScript client library over the coming weeks, which could include some of the following: + +* Support for private API docs, requiring login. +* File upload and download support in the JavaScript client & API docs. +* Comprehensive documentation for the JavaScript client library. +* Automatically including authentication details in the API doc code snippets. +* Adding authentication support in the command line client. +* Support for loading Swagger and other schemas in the JavaScript client. +* Improved support for documenting parameter schemas and response schemas. +* Refining the API documentation interaction modal. + +Once work on those refinements is complete, we'll be starting feature work +on realtime support, for the 3.7 release. + +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors +[funding]: funding.md +[api-docs]: ../topics/documenting-your-api.md +[js-docs]: ../topics/api-clients.md#javascript-client-library +[py-docs]: ../topics/api-clients.md#python-client-library diff --git a/docs/community/3.7-announcement.md b/docs/community/3.7-announcement.md new file mode 100644 index 0000000000..d1a39fa604 --- /dev/null +++ b/docs/community/3.7-announcement.md @@ -0,0 +1,130 @@ + + +# Django REST framework 3.7 + +The 3.7 release focuses on improvements to schema generation and the interactive API documentation. + +This release has been made possible by [Bayer](https://www.bayer.com/) who have sponsored the release. + + + +--- + +## Funding + +If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by +**[signing up for a paid plan][funding]**. + + +
+ +*As well as our release sponsor, we'd like to say thanks in particular our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://machinalis.com/), and [Rollbar](https://rollbar.com).* + +--- + +## Customizing API docs & schema generation. + +The schema generation introduced in 3.5 and the related API docs generation in 3.6 are both hugely powerful features, however they've been somewhat limited in cases where the view introspection isn't able to correctly identify the schema for a particular view. + +In order to try to address this we're now adding the ability for per-view customization of the API schema. The interface that we're adding for this allows either basic manual overrides over which fields should be included on a view, or for more complex programmatic overriding of the schema generation. We believe this release comprehensively addresses some of the existing shortcomings of the schema features. + +Let's take a quick look at using the new functionality... + +The `APIView` class has a `schema` attribute, that is used to control how the Schema for that particular view is generated. The default behaviour is to use the `AutoSchema` class. + + from rest_framework.views import APIView + from rest_framework.schemas import AutoSchema + + class CustomView(APIView): + schema = AutoSchema() # Included for demonstration only. This is the default behavior. + +We can remove a view from the API schema and docs, like so: + + class CustomView(APIView): + schema = None + +If we want to mostly use the default behavior, but additionally include some additional fields on a particular view, we can now do so easily... + + class CustomView(APIView): + schema = AutoSchema(manual_fields=[ + coreapi.Field('search', location='query') + ]) + +To ignore the automatic generation for a particular view, and instead specify the schema explicitly, we use the `ManualSchema` class instead... + + class CustomView(APIView): + schema = ManualSchema(fields=[...]) + +For more advanced behaviors you can subclass `AutoSchema` to provide for customized schema generation, and apply that to particular views. + + class CustomView(APIView): + schema = CustomizedSchemaGeneration() + +For full details on the new functionality, please see the [Schema Documentation][schema-docs]. + +--- + +## Django 2.0 support + +REST framework 3.7 supports Django versions 1.10, 1.11, and 2.0 alpha. + +--- + +## Minor fixes and improvements + +There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page for a complete listing. + +The number of [open tickets against the project](https://github.com/encode/django-rest-framework/issues) currently at its lowest number in quite some time, and we're continuing to focus on reducing these to a manageable amount. + +--- + +## Deprecations + +### `exclude_from_schema` + +Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` decorator and now `PendingDeprecation`. They will be moved to deprecated in the 3.8 release, and removed entirely in 3.9. + +For `APIView` you should instead set a `schema = None` attribute on the view class. + +For function based views the `@schema` decorator can be used to exclude the view from the schema, by using `@schema(None)`. + +### `DjangoFilterBackend` + +The `DjangoFilterBackend` was moved to pending deprecation in 3.5, and deprecated in 3.6. It has now been removed from the core framework. + +The functionality remains fully available, but is instead provided in the `django-filter` package. + +--- + +## What's next + +We're still planning to work on improving real-time support for REST framework by providing documentation on integrating with Django channels, as well adding support for more easily adding WebSocket support to existing HTTP endpoints. + +This will likely be timed so that any REST framework development here ties in with similar work on [API Star][api-star]. + +[funding]: funding.md +[schema-docs]: ../api-guide/schemas.md +[api-star]: https://github.com/encode/apistar diff --git a/docs/community/3.8-announcement.md b/docs/community/3.8-announcement.md new file mode 100644 index 0000000000..507299782d --- /dev/null +++ b/docs/community/3.8-announcement.md @@ -0,0 +1,97 @@ + + +# Django REST framework 3.8 + +The 3.8 release is a maintenance focused release resolving a large number of previously outstanding issues and laying +the foundations for future changes. + +--- + +## Funding + +If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its continued development by +**[signing up for a paid plan][funding]**. + + +*We'd like to say thanks in particular our premium backers, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Machinalis](https://machinalis.com/), and [Rollbar](https://rollbar.com).* + +--- + +## Breaking Changes + +### Altered the behaviour of `read_only` plus `default` on Field. + +[#5886][gh5886] `read_only` fields will now **always** be excluded from writable fields. + +Previously `read_only` fields when combined with a `default` value would use the `default` for create and update +operations. This was counter-intuitive in some circumstances and led to difficulties supporting dotted `source` +attributes on nullable relations. + +In order to maintain the old behaviour you may need to pass the value of `read_only` fields when calling `save()` in +the view: + + def perform_create(self, serializer): + serializer.save(owner=self.request.user) + +Alternatively you may override `save()` or `create()` or `update()` on the serializer as appropriate. + +--- + +## Deprecations + +### `action` decorator replaces `list_route` and `detail_route` + +[#5705][gh5705] `list_route` and `detail_route` have been merge into a single `action` decorator. This improves viewset action introspection, and will allow extra actions to be displayed in the Browsable API in future versions. + +Both `list_route` and `detail_route` are now pending deprecation. They will be deprecated in 3.9 and removed entirely +in 3.10. + +The new `action` decorator takes a boolean `detail` argument. + +* Replace `detail_route` uses with `@action(detail=True)`. +* Replace `list_route` uses with `@action(detail=False)`. + + +### `exclude_from_schema` + +Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` decorator are now deprecated. They will be removed entirely in 3.9. + +For `APIView` you should instead set a `schema = None` attribute on the view class. + +For function based views the `@schema` decorator can be used to exclude the view from the schema, by using `@schema(None)`. + +--- + +## Minor fixes and improvements + +There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page +for a complete listing. + + +## What's next + +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. + +[funding]: funding.md +[gh5886]: https://github.com/encode/django-rest-framework/issues/5886 +[gh5705]: https://github.com/encode/django-rest-framework/issues/5705 +[openapi]: https://www.openapis.org/ diff --git a/docs/community/3.9-announcement.md b/docs/community/3.9-announcement.md new file mode 100644 index 0000000000..1cf4464d6f --- /dev/null +++ b/docs/community/3.9-announcement.md @@ -0,0 +1,212 @@ + + +# Django REST framework 3.9 + +The 3.9 release gives access to _extra actions_ in the Browsable API, introduces composable permissions and built-in [OpenAPI][openapi] schema support. (Formerly known as Swagger) + +--- + +## Funding + +If you use REST framework commercially and would like to see this work continue, we strongly encourage you to invest in its 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, [Rover](https://www.rover.com/careers/), [Sentry](https://sentry.io/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), [Auklet](https://auklet.io/), [Rollbar](https://rollbar.com), [Cadre](https://cadre.com), [Load Impact](https://loadimpact.com/?utm_campaign=Sponsorship%20links&utm_source=drf&utm_medium=drf), and [Kloudless](https://hubs.ly/H0f30Lf0).* + +--- + +## Built-in OpenAPI schema support + +REST framework now has a first-pass at directly including OpenAPI schema support. (Formerly known as Swagger) + +Specifically: + +* There are now `OpenAPIRenderer`, and `JSONOpenAPIRenderer` classes that deal with encoding `coreapi.Document` instances into OpenAPI YAML or OpenAPI JSON. +* The `get_schema_view(...)` method now defaults to OpenAPI YAML, with CoreJSON as a secondary +option if it is selected via HTTP content negotiation. +* There is a new management command `generateschema`, which you can use to dump +the schema into your repository. + +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 + +schema_view = get_schema_view( + title='Server Monitoring API', + url='https://www.example.org/api/', + renderer_classes=[JSONOpenAPIRenderer] +) + +urlpatterns = [ + url('^schema.json$', schema_view), + ... +] +``` + +And here's how you can use the `generateschema` management command: + +```shell +$ python manage.py generateschema --format openapi > schema.yml +``` + +There's lots of different tooling that you can use for working with OpenAPI +schemas. One option that we're working on is the [API Star](https://docs.apistar.com/) +command line tool. + +You can use `apistar` to validate your API schema: + +```shell +$ apistar validate --path schema.json --format openapi +✓ Valid OpenAPI schema. +``` + +Or to build API documentation: + +```shell +$ apistar docs --path schema.json --format openapi +✓ Documentation built at "build/index.html". +``` + +API Star also includes a [dynamic client library](https://docs.apistar.com/client-library/) +that uses an API schema to automatically provide a client library interface for making requests. + +## Composable permission classes + +You can now compose permission classes using the and/or operators, `&` and `|`. + +For example... + +```python +permission_classes = [IsAuthenticated & (ReadOnly | IsAdmin)] +``` + +If you're using custom permission classes then make sure that you are subclassing +from `BasePermission` in order to enable this support. + +## ViewSet _Extra Actions_ available in the Browsable API + +Following the introduction of the `action` decorator in v3.8, _extra actions_ defined on a ViewSet are now available +from the Browsable API. + +![Extra Actions displayed in the Browsable API](https://user-images.githubusercontent.com/2370209/32976956-1ca9ab7e-cbf1-11e7-981a-a20cb1e83d63.png) + +When defined, a dropdown of "Extra Actions", appropriately filtered to detail/non-detail actions, is displayed. + +--- + +## Supported Versions + +REST framework 3.9 supports Django versions 1.11, 2.0, and 2.1. + +--- + +## Deprecations + +### `DjangoObjectPermissionsFilter` moved to third-party package. + +The `DjangoObjectPermissionsFilter` class is pending deprecation, will be deprecated in 3.10 and removed entirely in 3.11. + +It has been moved to the third-party [`djangorestframework-guardian`](https://github.com/rpkilby/django-rest-framework-guardian) +package. Please use this instead. + +### Router argument/method renamed to use `basename` for consistency. + +* The `Router.register` `base_name` argument has been renamed in favor of `basename`. +* The `Router.get_default_base_name` method has been renamed in favor of `Router.get_default_basename`. [#5990][gh5990] + +See [#5990][gh5990]. + +[gh5990]: https://github.com/encode/django-rest-framework/pull/5990 + +`base_name` and `get_default_base_name()` are pending deprecation. They will be deprecated in 3.10 and removed entirely in 3.11. + +### `action` decorator replaces `list_route` and `detail_route` + +Both `list_route` and `detail_route` are now deprecated in favour of the single `action` decorator. +They will be removed entirely in 3.10. + +The `action` decorator takes a boolean `detail` argument. + +* Replace `detail_route` uses with `@action(detail=True)`. +* Replace `list_route` uses with `@action(detail=False)`. + +### `exclude_from_schema` + +Both `APIView.exclude_from_schema` and the `exclude_from_schema` argument to the `@api_view` have now been removed. + +For `APIView` you should instead set a `schema = None` attribute on the view class. + +For function-based views the `@schema` decorator can be used to exclude the view from the schema, by using `@schema(None)`. + +--- + +## Minor fixes and improvements + +There are a large number of minor fixes and improvements in this release. See the [release notes](release-notes.md) page for a complete listing. + + +## What's next + +We're planning to iteratively work towards OpenAPI becoming the standard schema +representation. This will mean that the `coreapi` dependency will gradually become +removed, and we'll instead generate the schema directly, rather than building +a CoreAPI `Document` object. + +OpenAPI has clearly become the standard for specifying Web APIs, so there's not +much value any more in our schema-agnostic document model. Making this change +will mean that we'll more easily be able to take advantage of the full set of +OpenAPI functionality. + +This will also make a wider range of tooling available. + +We'll focus on continuing to develop the [API Star](https://docs.apistar.com/) +library and client tool into a recommended option for generating API docs, +validating API schemas, and providing a dynamic client library. + +There's also a huge amount of ongoing work on maturing the ASGI landscape, +with the possibility that some of this work will eventually [feed back into +Django](https://www.aeracode.org/2018/06/04/django-async-roadmap/). + +There will be further work on the [Uvicorn](https://www.uvicorn.org/) +web server, as well as lots of functionality planned for the [Starlette](https://www.starlette.io/) +web framework, which is building a foundational set of tooling for working with +ASGI. + + +[funding]: funding.md +[gh5886]: https://github.com/encode/django-rest-framework/issues/5886 +[gh5705]: https://github.com/encode/django-rest-framework/issues/5705 +[openapi]: https://www.openapis.org/ +[sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors diff --git a/docs/topics/contributing.md b/docs/community/contributing.md similarity index 91% rename from docs/topics/contributing.md rename to docs/community/contributing.md index ed7717ae2f..cb67100d2b 100644 --- a/docs/topics/contributing.md +++ b/docs/community/contributing.md @@ -48,9 +48,15 @@ Getting involved in triaging incoming issues is a good way to start contributing # Development -To start developing on Django REST framework, clone the repo: +To start developing on Django REST framework, first create a Fork from the +[Django REST Framework repo][repo] on GitHub. - git clone git@github.com:tomchristie/django-rest-framework.git +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 + +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. @@ -59,7 +65,7 @@ Changes should broadly follow the [PEP 8][pep-8] style conventions, and we recom 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 -r requirements.txt @@ -115,7 +121,7 @@ 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. @@ -198,15 +204,17 @@ If you want to draw attention to a note or warning, use a pair of enclosing line --- -[cite]: http://www.w3.org/People/Berners-Lee/FAQ.html +[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]: http://stackexchange.com/filters/66475/rest-framework -[issues]: https://github.com/tomchristie/django-rest-framework/issues?state=open -[pep-8]: http://www.python.org/dev/peps/pep-0008/ +[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 [pull-requests]: https://help.github.com/articles/using-pull-requests [tox]: https://tox.readthedocs.io/en/latest/ -[markdown]: http://daringfireball.net/projects/markdown/basics -[docs]: https://github.com/tomchristie/django-rest-framework/tree/master/docs +[markdown]: https://daringfireball.net/projects/markdown/basics +[docs]: https://github.com/encode/django-rest-framework/tree/master/docs [mou]: http://mouapp.com/ +[repo]: https://github.com/encode/django-rest-framework +[how-to-fork]: https://help.github.com/articles/fork-a-repo/ diff --git a/docs/community/funding.md b/docs/community/funding.md new file mode 100644 index 0000000000..662e3d5d9a --- /dev/null +++ b/docs/community/funding.md @@ -0,0 +1,398 @@ + + + + +# Funding + +If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan. + +**We believe that collaboratively funded software can offer outstanding returns on investment, by encouraging our users to collectively share the cost of development.** + +Signing up for a paid plan will: + +* Directly contribute to faster releases, more features, and higher quality software. +* Allow more time to be invested in documentation, issue triage, and community support. +* Safeguard the future development of REST framework. + +REST framework continues to be open-source and permissively licensed, but we firmly believe it is in the commercial best-interest for users of the project to invest in its ongoing development. + +--- + +## 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.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. +* Around 80-90 issues and pull requests closed per month since Tom Christie started working on the project full-time. +* A community & operations manager position part-time for 4 months, helping mature the business and grow sponsorship. +* Contracting development time for the work on the JavaScript client library and API documentation tooling. + +--- + +## 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. +* 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. + +Sign up for a paid plan today, and help ensure that REST framework becomes a sustainable, full-time funded project. + +--- + +## What our sponsors and users say + +> As a developer, Django REST framework feels like an obvious and natural extension to all the great things that make up Django and it's community. Getting started is easy while providing simple abstractions which makes it flexible and customizable. Contributing and supporting Django REST framework helps ensure its future and one way or another it also helps Django, and the Python ecosystem. +> +> — José Padilla, Django REST framework contributor + +  + +> 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. +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 + +--- + +## Individual plan + +This subscription is recommended for individuals with an interest in seeing REST framework continue to improve. + +If you are using REST framework as a full-time employee, consider recommending that your company takes out a [corporate plan](#corporate-plans). + +
+
+
+
+ {{ symbol }} + {{ rates.personal1 }} + /month{% if vat %} +VAT{% endif %} +
+
Individual
+
+
+ Support ongoing development +
+
+ Credited on the site +
+
+ + + +
+
+
+
+ +*Billing is monthly and you can cancel at any time.* + +--- + +## Corporate plans + +These subscriptions are recommended for companies and organizations using REST framework either publicly or privately. + +In exchange for funding you'll also receive advertising space on our site, allowing you to **promote your company or product to many tens of thousands of developers worldwide**. + +Our professional and premium plans also include **priority support**. At any time your engineers can escalate an issue or discussion group thread, and we'll ensure it gets a guaranteed response within the next working day. + +
+
+
+
+ {{ symbol }} + {{ rates.corporate1 }} + /month{% if vat %} +VAT{% endif %} +
+
Basic
+
+
+ Support ongoing development +
+
+ Funding page ad placement +
+
+ +
+
+
+
+
+ {{ symbol }} + {{ rates.corporate2 }} + /month{% if vat %} +VAT{% endif %} +
+
Professional
+
+
+ Support ongoing development +
+
+ Sidebar ad placement +
+
+ Priority support for your engineers +
+
+ +
+
+
+
+
+ {{ symbol }} + {{ rates.corporate3 }} + /month{% if vat %} +VAT{% endif %} +
+
Premium
+
+
+ Support ongoing development +
+
+ Homepage ad placement +
+
+ Sidebar ad placement +
+
+ Priority support for your engineers +
+
+ +
+
+
+ +
+ +*Billing is monthly and you can cancel at any time.* + +Once you've signed up, we will contact you via email and arrange your ad placements on the site. + +For further enquires please contact funding@django-rest-framework.org. + +--- + +## Accountability + +In an effort to keep the project as transparent as possible, we are releasing [monthly progress reports](https://www.encode.io/reports/march-2018/) and regularly include financial reports and cost breakdowns. + + + + +
+
+
+

Stay up to date, with our monthly progress reports...

+
+ + +
+
+ + +
+ +
+
+
+
+ + + +--- + +## Frequently asked questions + +**Q: Can you issue monthly invoices?** +A: Yes, we are happy to issue monthly invoices. Please just email us and let us know who to issue the invoice to (name and address) and which email address to send it to each month. + +**Q: Does sponsorship include VAT?** +A: Sponsorship is VAT exempt. + +**Q: Do I have to sign up for a certain time period?** +A: No, we appreciate your support for any time period that is convenient for you. Also, you can cancel your sponsorship anytime. + +**Q: Can I pay yearly? Can I pay upfront fox X amount of months at a time?** +A: We are currently only set up to accept monthly payments. However, if you'd like to support Django REST framework and you can only do yearly/upfront payments, we are happy to work with you and figure out a convenient solution. + +**Q: Are you only looking for corporate sponsors?** +A: No, we value individual sponsors just as much as corporate sponsors and appreciate any kind of support. + +--- + +## Our sponsors + +
+ + diff --git a/docs/community/jobs.md b/docs/community/jobs.md new file mode 100644 index 0000000000..5f3d60b550 --- /dev/null +++ b/docs/community/jobs.md @@ -0,0 +1,39 @@ +# Jobs + +Looking for a new Django REST Framework related role? On this site we provide a list of job resources that may be helpful. It's also worth checking out if any of [our sponsors are hiring][drf-funding]. + + +## Places to look for Django REST Framework Jobs + +* [https://www.djangoproject.com/community/jobs/][djangoproject-website] +* [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://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://www.remotepython.com/jobs/][remotepython-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]. + +Wonder how else you can help? One of the best ways you can help Django REST Framework is to ask interviewers if their company is signed up for [REST Framework sponsorship][drf-funding] yet. + + +[djangoproject-website]: https://www.djangoproject.com/community/jobs/ +[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 +[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 +[remotepython-com]: https://www.remotepython.com/jobs/ +[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/topics/kickstarter-announcement.md b/docs/community/kickstarter-announcement.md similarity index 70% rename from docs/topics/kickstarter-announcement.md rename to docs/community/kickstarter-announcement.md index 78c5cce6f9..27e77ceb59 100644 --- a/docs/topics/kickstarter-announcement.md +++ b/docs/community/kickstarter-announcement.md @@ -47,8 +47,8 @@ Our platinum sponsors have each made a hugely substantial contribution to the fu @@ -102,41 +102,41 @@ Our gold sponsors include companies large and small. Many thanks for their signi ### Silver sponsors -The serious financial contribution that our silver sponsors have made is very much appreciated. I'd like to say a particular thank you to individuals who have choosen to privately support the project at this level. +The serious financial contribution that our silver sponsors have made is very much appreciated. I'd like to say a particular thank you to individuals who have chosen to privately support the project at this level.
-*Many thanks to all our [wonderful sponsors][sponsors], and in particular to our premium backers, [Rover](http://jobs.rover.com/), [Sentry](https://getsentry.com/welcome/), [Stream](https://getstream.io/?utm_source=drf&utm_medium=banner&utm_campaign=drf), and [Machinalis](http://www.machinalis.com/#services).* +*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).* --- @@ -86,15 +85,18 @@ The initial aim is to provide a single full-time position on REST framework. REST framework requires the following: -* Python (2.7, 3.2, 3.3, 3.4, 3.5) -* Django (1.8, 1.9, 1.10) +* Python (3.5, 3.6, 3.7, 3.8) +* Django (1.11, 2.0, 2.1, 2.2, 3.0) + +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. -* [django-filter][django-filter] (0.9.2+) - Filtering support. -* [django-crispy-forms][django-crispy-forms] - Improved HTML display for filtering. +* [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-guardian][django-guardian] (1.1.1+) - Object level permissions support. ## Installation @@ -107,23 +109,23 @@ Install using `pip`, including any optional packages you want... ...or clone the project from github. - git clone git@github.com:tomchristie/django-rest-framework.git + git clone https://github.com/encode/django-rest-framework 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', namespace='rest_framework')) + url(r'^api-auth/', include('rest_framework.urls')) ] -Note that the URL path can be whatever you want, but you must include `'rest_framework.urls'` with the `'rest_framework'` namespace. You may leave out the namespace in Django 1.9+, and REST framework will set it for you. +Note that the URL path can be whatever you want. ## Example @@ -150,11 +152,11 @@ Here's our project's root `urls.py` module: from django.contrib.auth.models import User 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') + # Serializers define the API representation. + class UserSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = User + fields = ['url', 'username', 'email', 'is_staff'] # ViewSets define the view behavior. class UserViewSet(viewsets.ModelViewSet): @@ -178,78 +180,6 @@ You can now open the API in your browser at [http://127.0.0.1:8000/](http://127. Can't wait to get started? The [quickstart guide][quickstart] is the fastest way to get up and running, and building APIs with REST framework. -## Tutorial - -The tutorial will walk you through the building blocks that make up REST framework. It'll take a little while to get through, but it'll give you a comprehensive understanding of how everything fits together, and is highly recommended reading. - -* [1 - Serialization][tut-1] -* [2 - Requests & Responses][tut-2] -* [3 - Class-based views][tut-3] -* [4 - Authentication & permissions][tut-4] -* [5 - Relationships & hyperlinked APIs][tut-5] -* [6 - Viewsets & routers][tut-6] -* [7 - Schemas & client libraries][tut-7] - -There is a live example API of the finished tutorial API for testing purposes, [available here][sandbox]. - -## API Guide - -The API guide is your complete reference manual to all the functionality provided by REST framework. - -* [Requests][request] -* [Responses][response] -* [Views][views] -* [Generic views][generic-views] -* [Viewsets][viewsets] -* [Routers][routers] -* [Parsers][parsers] -* [Renderers][renderers] -* [Serializers][serializers] -* [Serializer fields][fields] -* [Serializer relations][relations] -* [Validators][validators] -* [Authentication][authentication] -* [Permissions][permissions] -* [Throttling][throttling] -* [Filtering][filtering] -* [Pagination][pagination] -* [Versioning][versioning] -* [Content negotiation][contentnegotiation] -* [Metadata][metadata] -* [Schemas][schemas] -* [Format suffixes][formatsuffixes] -* [Returning URLs][reverse] -* [Exceptions][exceptions] -* [Status codes][status] -* [Testing][testing] -* [Settings][settings] - -## Topics - -General guides to using REST framework. - -* [Documenting your API][documenting-your-api] -* [API Clients][api-clients] -* [Internationalization][internationalization] -* [AJAX, CSRF & CORS][ajax-csrf-cors] -* [HTML & Forms][html-and-forms] -* [Browser enhancements][browser-enhancements] -* [The Browsable API][browsableapi] -* [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] -* [Third Party Resources][third-party-resources] -* [Contributing to REST framework][contributing] -* [Project management][project-management] -* [3.0 Announcement][3.0-announcement] -* [3.1 Announcement][3.1-announcement] -* [3.2 Announcement][3.2-announcement] -* [3.3 Announcement][3.3-announcement] -* [3.4 Announcement][3.4-announcement] -* [3.5 Announcement][3.5-announcement] -* [Kickstarter Announcement][kickstarter-announcement] -* [Mozilla Grant][mozilla-grant] -* [Funding][funding] -* [Release Notes][release-notes] - ## Development See the [Contribution guidelines][contributing] for information on how to clone @@ -260,7 +190,7 @@ Framework. 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. -[Paid support is available][paid-support] from [DabApps][dabapps], and can include work on REST framework core, or support with building your REST framework API. Please [contact DabApps][contact-dabapps] if you'd like to discuss commercial support options. +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. @@ -275,17 +205,22 @@ Send a description of the issue via email to [rest-framework-security@googlegrou ## License -Copyright (c) 2011-2016, Tom Christie +Copyright © 2011-present, [Encode OSS Ltd](https://www.encode.io/). All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -Redistributions of source code must retain the above copyright notice, this -list of conditions and the following disclaimer. -Redistributions in binary form must reproduce the above copyright notice, this -list of conditions and the following disclaimer in the documentation and/or -other materials provided with the distribution. +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED @@ -298,94 +233,38 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -[mozilla]: http://www.mozilla.org/en-US/about/ +[mozilla]: https://www.mozilla.org/en-US/about/ [redhat]: https://www.redhat.com/ [heroku]: https://www.heroku.com/ [eventbrite]: https://www.eventbrite.co.uk/about/ -[coreapi]: http://pypi.python.org/pypi/coreapi/ -[markdown]: http://pypi.python.org/pypi/Markdown/ -[django-filter]: http://pypi.python.org/pypi/django-filter -[django-crispy-forms]: https://github.com/maraujop/django-crispy-forms -[django-guardian]: https://github.com/lukaszb/django-guardian -[0.4]: https://github.com/tomchristie/django-rest-framework/tree/0.4.X -[image]: img/quickstart.png +[coreapi]: https://pypi.org/project/coreapi/ +[markdown]: https://pypi.org/project/Markdown/ +[pygments]: https://pypi.org/project/Pygments/ +[django-filter]: https://pypi.org/project/django-filter/ +[django-guardian]: https://github.com/django-guardian/django-guardian [index]: . [oauth1-section]: api-guide/authentication/#django-rest-framework-oauth [oauth2-section]: api-guide/authentication/#django-oauth-toolkit [serializer-section]: api-guide/serializers#serializers [modelserializer-section]: api-guide/serializers#modelserializer [functionview-section]: api-guide/views#function-based-views -[sandbox]: http://restframework.herokuapp.com/ +[sandbox]: https://restframework.herokuapp.com/ [sponsors]: https://fund.django-rest-framework.org/topics/funding/#our-sponsors [quickstart]: tutorial/quickstart.md -[tut-1]: tutorial/1-serialization.md -[tut-2]: tutorial/2-requests-and-responses.md -[tut-3]: tutorial/3-class-based-views.md -[tut-4]: tutorial/4-authentication-and-permissions.md -[tut-5]: tutorial/5-relationships-and-hyperlinked-apis.md -[tut-6]: tutorial/6-viewsets-and-routers.md -[tut-7]: tutorial/7-schemas-and-client-libraries.md - -[request]: api-guide/requests.md -[response]: api-guide/responses.md -[views]: api-guide/views.md + [generic-views]: api-guide/generic-views.md [viewsets]: api-guide/viewsets.md [routers]: api-guide/routers.md -[parsers]: api-guide/parsers.md -[renderers]: api-guide/renderers.md [serializers]: api-guide/serializers.md -[fields]: api-guide/fields.md -[relations]: api-guide/relations.md -[validators]: api-guide/validators.md [authentication]: api-guide/authentication.md -[permissions]: api-guide/permissions.md -[throttling]: api-guide/throttling.md -[filtering]: api-guide/filtering.md -[pagination]: api-guide/pagination.md -[versioning]: api-guide/versioning.md -[contentnegotiation]: api-guide/content-negotiation.md -[metadata]: api-guide/metadata.md -[schemas]: api-guide/schemas.md -[formatsuffixes]: api-guide/format-suffixes.md -[reverse]: api-guide/reverse.md -[exceptions]: api-guide/exceptions.md -[status]: api-guide/status-codes.md -[testing]: api-guide/testing.md -[settings]: api-guide/settings.md - -[documenting-your-api]: topics/documenting-your-api.md -[api-clients]: topics/api-clients.md -[internationalization]: topics/internationalization.md -[ajax-csrf-cors]: topics/ajax-csrf-cors.md -[html-and-forms]: topics/html-and-forms.md -[browser-enhancements]: topics/browser-enhancements.md -[browsableapi]: topics/browsable-api.md -[rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md -[contributing]: topics/contributing.md -[project-management]: topics/project-management.md -[third-party-resources]: topics/third-party-resources.md -[3.0-announcement]: topics/3.0-announcement.md -[3.1-announcement]: topics/3.1-announcement.md -[3.2-announcement]: topics/3.2-announcement.md -[3.3-announcement]: topics/3.3-announcement.md -[3.4-announcement]: topics/3.4-announcement.md -[3.5-announcement]: topics/3.5-announcement.md -[kickstarter-announcement]: topics/kickstarter-announcement.md -[mozilla-grant]: topics/mozilla-grant.md -[funding]: topics/funding.md -[release-notes]: topics/release-notes.md - -[tox]: http://testrun.org/tox/latest/ + +[contributing]: community/contributing.md +[funding]: community/funding.md [group]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework [botbot]: https://botbot.me/freenode/restframework/ -[stack-overflow]: http://stackoverflow.com/ -[django-rest-framework-tag]: http://stackoverflow.com/questions/tagged/django-rest-framework -[django-tag]: http://stackoverflow.com/questions/tagged/django +[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 -[paid-support]: http://dabapps.com/services/build/api-development/ -[dabapps]: http://dabapps.com -[contact-dabapps]: http://dabapps.com/contact/ [twitter]: https://twitter.com/_tomchristie diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md deleted file mode 100644 index e6220f4277..0000000000 --- a/docs/topics/2.2-announcement.md +++ /dev/null @@ -1,159 +0,0 @@ -# Django REST framework 2.2 - -The 2.2 release represents an important point for REST framework, with the addition of Python 3 support, and the introduction of an official deprecation policy. - -## Python 3 support - -Thanks to some fantastic work from [Xavier Ordoquy][xordoquy], Django REST framework 2.2 now supports Python 3. You'll need to be running Django 1.5, and it's worth keeping in mind that Django's Python 3 support is currently [considered experimental][django-python-3]. - -Django 1.6's Python 3 support is expected to be officially labeled as 'production-ready'. - -If you want to start ensuring that your own projects are Python 3 ready, we can highly recommend Django's [Porting to Python 3][porting-python-3] documentation. - -Django REST framework's Python 2.6 support now requires 2.6.5 or above, in line with [Django 1.5's Python compatibility][python-compat]. - -## Deprecation policy - -We've now introduced an official deprecation policy, which is in line with [Django's deprecation policy][django-deprecation-policy]. This policy will make it easy for you to continue to track the latest, greatest version of REST framework. - -The timeline for deprecation works as follows: - -* Version 2.2 introduces some API changes as detailed in the release notes. It remains fully backwards compatible with 2.1, but will raise `PendingDeprecationWarning` warnings if you use bits of API that are due to be deprecated. These warnings are silent by default, but can be explicitly enabled when you're ready to start migrating any required changes. For example if you start running your tests using `python -Wd manage.py test`, you'll be warned of any API changes you need to make. - -* Version 2.3 will escalate these warnings to `DeprecationWarning`, which is loud by default. - -* Version 2.4 will remove the deprecated bits of API entirely. - -Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change. - -## Community - -As of the 2.2 merge, we've also hit an impressive milestone. The number of committers listed in [the credits][credits], is now at over **one hundred individuals**. Each name on that list represents at least one merged pull request, however large or small. - -Our [mailing list][mailing-list] and #restframework IRC channel are also very active, and we've got a really impressive rate of development both on REST framework itself, and on third party packages such as the great [django-rest-framework-docs][django-rest-framework-docs] package from [Marc Gibbons][marcgibbons]. - ---- - -## API changes - -The 2.2 release makes a few changes to the API, in order to make it more consistent, simple, and easier to use. - -### Cleaner to-many related fields - -The `ManyRelatedField()` style is being deprecated in favor of a new `RelatedField(many=True)` syntax. - -For example, if a user is associated with multiple questions, which we want to represent using a primary key relationship, we might use something like the following: - - class UserSerializer(serializers.HyperlinkedModelSerializer): - questions = serializers.PrimaryKeyRelatedField(many=True) - - class Meta: - fields = ('username', 'questions') - -The new syntax is cleaner and more obvious, and the change will also make the documentation cleaner, simplify the internal API, and make writing custom relational fields easier. - -The change also applies to serializers. If you have a nested serializer, you should start using `many=True` for to-many relationships. For example, a serializer representation of an Album that can contain many Tracks might look something like this: - - class TrackSerializer(serializer.ModelSerializer): - class Meta: - model = Track - fields = ('name', 'duration') - - class AlbumSerializer(serializer.ModelSerializer): - tracks = TrackSerializer(many=True) - - class Meta: - model = Album - fields = ('album_name', 'artist', 'tracks') - -Additionally, the change also applies when serializing or deserializing data. For example to serialize a queryset of models you should now use the `many=True` flag. - - serializer = SnippetSerializer(Snippet.objects.all(), many=True) - serializer.data - -This more explicit behavior on serializing and deserializing data [makes integration with non-ORM backends such as MongoDB easier][564], as instances to be serialized can include the `__iter__` method, without incorrectly triggering list-based serialization, or requiring workarounds. - -The implicit to-many behavior on serializers, and the `ManyRelatedField` style classes will continue to function, but will raise a `PendingDeprecationWarning`, which can be made visible using the `-Wd` flag. - -**Note**: If you need to forcibly turn off the implicit "`many=True` for `__iter__` objects" behavior, you can now do so by specifying `many=False`. This will become the default (instead of the current default of `None`) once the deprecation of the implicit behavior is finalised in version 2.4. - -### Cleaner optional relationships - -Serializer relationships for nullable Foreign Keys will change from using the current `null=True` flag, to instead using `required=False`. - -For example, is a user account has an optional foreign key to a company, that you want to express using a hyperlink, you might use the following field in a `Serializer` class: - - current_company = serializers.HyperlinkedRelatedField(required=False) - -This is in line both with the rest of the serializer fields API, and with Django's `Form` and `ModelForm` API. - -Using `required` throughout the serializers API means you won't need to consider if a particular field should take `blank` or `null` arguments instead of `required`, and also means there will be more consistent behavior for how fields are treated when they are not present in the incoming data. - -The `null=True` argument will continue to function, and will imply `required=False`, but will raise a `PendingDeprecationWarning`. - -### Cleaner CharField syntax - -The `CharField` API previously took an optional `blank=True` argument, which was intended to differentiate between null CharField input, and blank CharField input. - -In keeping with Django's CharField API, REST framework's `CharField` will only ever return the empty string, for missing or `None` inputs. The `blank` flag will no longer be in use, and you should instead just use the `required=` flag. For example: - - extra_details = CharField(required=False) - -The `blank` keyword argument will continue to function, but will raise a `PendingDeprecationWarning`. - -### Simpler object-level permissions - -Custom permissions classes previously used the signature `.has_permission(self, request, view, obj=None)`. This method would be called twice, firstly for the global permissions check, with the `obj` parameter set to `None`, and again for the object-level permissions check when appropriate, with the `obj` parameter set to the relevant model instance. - -The global permissions check and object-level permissions check are now separated into two separate methods, which gives a cleaner, more obvious API. - -* Global permission checks now use the `.has_permission(self, request, view)` signature. -* Object-level permission checks use a new method `.has_object_permission(self, request, view, obj)`. - -For example, the following custom permission class: - - class IsOwner(permissions.BasePermission): - """ - Custom permission to only allow owners of an object to view or edit it. - Model instances are expected to include an `owner` attribute. - """ - - def has_permission(self, request, view, obj=None): - if obj is None: - # Ignore global permissions check - return True - - return obj.owner == request.user - -Now becomes: - - class IsOwner(permissions.BasePermission): - """ - Custom permission to only allow owners of an object to view or edit it. - Model instances are expected to include an `owner` attribute. - """ - - def has_object_permission(self, request, view, obj): - return obj.owner == request.user - -If you're overriding the `BasePermission` class, the old-style signature will continue to function, and will correctly handle both global and object-level permissions checks, but its use will raise a `PendingDeprecationWarning`. - -Note also that the usage of the internal APIs for permission checking on the `View` class has been cleaned up slightly, and is now documented and subject to the deprecation policy in all future versions. - -### More explicit hyperlink relations behavior - -When using a serializer with a `HyperlinkedRelatedField` or `HyperlinkedIdentityField`, the hyperlinks would previously use absolute URLs if the serializer context included a `'request'` key, and fall back to using relative URLs otherwise. This could lead to non-obvious behavior, as it might not be clear why some serializers generated absolute URLs, and others do not. - -From version 2.2 onwards, serializers with hyperlinked relationships *always* require a `'request'` key to be supplied in the context dictionary. The implicit behavior will continue to function, but its use will raise a `PendingDeprecationWarning`. - -[xordoquy]: https://github.com/xordoquy -[django-python-3]: https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3 -[porting-python-3]: https://docs.djangoproject.com/en/dev/topics/python3/ -[python-compat]: https://docs.djangoproject.com/en/dev/releases/1.5/#python-compatibility -[django-deprecation-policy]: https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy -[credits]: http://www.django-rest-framework.org/topics/credits -[mailing-list]: https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework -[django-rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs -[marcgibbons]: https://github.com/marcgibbons/ -[issues]: https://github.com/tomchristie/django-rest-framework/issues -[564]: https://github.com/tomchristie/django-rest-framework/issues/564 diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md deleted file mode 100644 index d9bab39dca..0000000000 --- a/docs/topics/2.3-announcement.md +++ /dev/null @@ -1,264 +0,0 @@ -# Django REST framework 2.3 - -REST framework 2.3 makes it even quicker and easier to build your Web APIs. - -## ViewSets and Routers - -The 2.3 release introduces the [ViewSet][viewset] and [Router][router] classes. - -A viewset is simply a type of class-based view that allows you to group multiple views into a single common class. - -Routers allow you to automatically determine the URLconf for your viewset classes. - -As an example of just how simple REST framework APIs can now be, here's an API written in a single `urls.py` module: - - """ - A REST framework API for viewing and editing users and groups. - """ - from django.conf.urls.defaults import url, include - from django.contrib.auth.models import User, Group - from rest_framework import viewsets, routers - - - # ViewSets define the view behavior. - class UserViewSet(viewsets.ModelViewSet): - model = User - - class GroupViewSet(viewsets.ModelViewSet): - model = Group - - - # Routers provide an easy way of automatically determining the URL conf - router = routers.DefaultRouter() - router.register(r'users', UserViewSet) - router.register(r'groups', GroupViewSet) - - - # 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')) - ] - -The best place to get started with ViewSets and Routers is to take a look at the [newest section in the tutorial][part-6], which demonstrates their usage. - -## Simpler views - -This release rationalises the API and implementation of the generic views, dropping the dependency on Django's `SingleObjectMixin` and `MultipleObjectMixin` classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with. - -This improvement is reflected in improved documentation for the `GenericAPIView` base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses. - -## Easier Serializers - -REST framework lets you be totally explicit regarding how you want to represent relationships, allowing you to choose between styles such as hyperlinking or primary key relationships. - -The ability to specify exactly how you want to represent relationships is powerful, but it also introduces complexity. In order to keep things more simple, REST framework now allows you to include reverse relationships simply by including the field name in the `fields` metadata of the serializer class. - -For example, in REST framework 2.2, reverse relationships needed to be included explicitly on a serializer class. - - class BlogSerializer(serializers.ModelSerializer): - comments = serializers.PrimaryKeyRelatedField(many=True) - - class Meta: - model = Blog - fields = ('id', 'title', 'created', 'comments') - -As of 2.3, you can simply include the field name, and the appropriate serializer field will automatically be used for the relationship. - - class BlogSerializer(serializers.ModelSerializer): - """ - Don't need to specify the 'comments' field explicitly anymore. - """ - class Meta: - model = Blog - fields = ('id', 'title', 'created', 'comments') - -Similarly, you can now easily include the primary key in hyperlinked relationships, simply by adding the field name to the metadata. - - class BlogSerializer(serializers.HyperlinkedModelSerializer): - """ - This is a hyperlinked serializer, which default to using - a field named 'url' as the primary identifier. - Note that we can now easily also add in the 'id' field. - """ - class Meta: - model = Blog - fields = ('url', 'id', 'title', 'created', 'comments') - -## More flexible filtering - -The `FILTER_BACKEND` setting has moved to pending deprecation, in favor of a `DEFAULT_FILTER_BACKENDS` setting that takes a *list* of filter backend classes, instead of a single filter backend class. - -The generic view `filter_backend` attribute has also been moved to pending deprecation in favor of a `filter_backends` setting. - -Being able to specify multiple filters will allow for more flexible, powerful behavior. New filter classes to handle searching and ordering of results are planned to be released shortly. - ---- - -# API Changes - -## Simplified generic view classes - -The functionality provided by `SingleObjectAPIView` and `MultipleObjectAPIView` base classes has now been moved into the base class `GenericAPIView`. The implementation of this base class is simple enough that providing subclasses for the base classes of detail and list views is somewhat unnecessary. - -Additionally the base generic view no longer inherits from Django's `SingleObjectMixin` or `MultipleObjectMixin` classes, simplifying the implementation, and meaning you don't need to cross-reference across to Django's codebase. - -Using the `SingleObjectAPIView` and `MultipleObjectAPIView` base classes continues to be supported, but will raise a `PendingDeprecationWarning`. You should instead simply use `GenericAPIView` as the base for any generic view subclasses. - -### Removed attributes - -The following attributes and methods, were previously present as part of Django's generic view implementations, but were unneeded and unused and have now been entirely removed. - -* context_object_name -* get_context_data() -* get_context_object_name() - -The following attributes and methods, which were previously present as part of Django's generic view implementations have also been entirely removed. - -* paginator_class -* get_paginator() -* get_allow_empty() -* get_slug_field() - -There may be cases when removing these bits of API might mean you need to write a little more code if your view has highly customized behavior, but generally we believe that providing a coarser-grained API will make the views easier to work with, and is the right trade-off to make for the vast majority of cases. - -Note that the listed attributes and methods have never been a documented part of the REST framework API, and as such are not covered by the deprecation policy. - -### Simplified methods - -The `get_object` and `get_paginate_by` methods no longer take an optional queryset argument. This makes overridden these methods more obvious, and a little more simple. - -Using an optional queryset with these methods continues to be supported, but will raise a `PendingDeprecationWarning`. - -The `paginate_queryset` method no longer takes a `page_size` argument, or returns a four-tuple of pagination information. Instead it simply takes a queryset argument, and either returns a `page` object with an appropriate page size, or returns `None`, if pagination is not configured for the view. - -Using the `page_size` argument is still supported and will trigger the old-style return type, but will raise a `PendingDeprecationWarning`. - -### Deprecated attributes - -The following attributes are used to control queryset lookup, and have all been moved into a pending deprecation state. - -* pk_url_kwarg = 'pk' -* slug_url_kwarg = 'slug' -* slug_field = 'slug' - -Their usage is replaced with a single attribute: - -* lookup_field = 'pk' - -This attribute is used both as the regex keyword argument in the URL conf, and as the model field to filter against when looking up a model instance. To use non-pk based lookup, simply set the `lookup_field` argument to an alternative field, and ensure that the keyword argument in the url conf matches the field name. - -For example, a view with 'username' based lookup might look like this: - - class UserDetail(generics.RetrieveAPIView): - lookup_field = 'username' - queryset = User.objects.all() - serializer_class = UserSerializer - -And would have the following entry in the urlconf: - - url(r'^users/(?P\w+)/$', UserDetail.as_view()), - -Usage of the old-style attributes continues to be supported, but will raise a `PendingDeprecationWarning`. - -The `allow_empty` attribute is also deprecated. To use `allow_empty=False` style behavior you should explicitly override `get_queryset` and raise an `Http404` on empty querysets. - -For example: - - class DisallowEmptyQuerysetMixin(object): - def get_queryset(self): - queryset = super(DisallowEmptyQuerysetMixin, self).get_queryset() - if not queryset.exists(): - raise Http404 - return queryset - -In our opinion removing lesser-used attributes like `allow_empty` helps us move towards simpler generic view implementations, making them more obvious to use and override, and re-enforcing the preferred style of developers writing their own base classes and mixins for custom behavior rather than relying on the configurability of the generic views. - -## Simpler URL lookups - -The `HyperlinkedRelatedField` class now takes a single optional `lookup_field` argument, that replaces the `pk_url_kwarg`, `slug_url_kwarg`, and `slug_field` arguments. - -For example, you might have a field that references it's relationship by a hyperlink based on a slug field: - - account = HyperlinkedRelatedField(read_only=True, - lookup_field='slug', - view_name='account-detail') - -Usage of the old-style attributes continues to be supported, but will raise a `PendingDeprecationWarning`. - -## FileUploadParser - -2.3 adds a `FileUploadParser` parser class, that supports raw file uploads, in addition to the existing multipart upload support. - -## DecimalField - -2.3 introduces a `DecimalField` serializer field, which returns `Decimal` instances. - -For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering `Decimal` instances to your renderer implementation. - -## ModelSerializers and reverse relationships - -The support for adding reverse relationships to the `fields` option on a `ModelSerializer` class means that the `get_related_field` and `get_nested_field` method signatures have now changed. - -In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now `(self, model_field, related_model, to_many)`. For reverse relationships `model_field` will be `None`. - -The old-style signature will continue to function but will raise a `PendingDeprecationWarning`. - -## View names and descriptions - -The mechanics of how the names and descriptions used in the browsable API are generated has been modified and cleaned up somewhat. - -If you've been customizing this behavior, for example perhaps to use `rst` markup for the browsable API, then you'll need to take a look at the implementation to see what updates you need to make. - -Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated. - ---- - -# Other notes - -## More explicit style - -The usage of `model` attribute in generic Views is still supported, but it's usage is generally being discouraged throughout the documentation, in favour of the setting the more explicit `queryset` and `serializer_class` attributes. - -For example, the following is now the recommended style for using generic views: - - class AccountListView(generics.RetrieveAPIView): - queryset = MyModel.objects.all() - serializer_class = MyModelSerializer - -Using an explicit `queryset` and `serializer_class` attributes makes the functioning of the view more clear than using the shortcut `model` attribute. - -It also makes the usage of the `get_queryset()` or `get_serializer_class()` methods more obvious. - - class AccountListView(generics.RetrieveAPIView): - serializer_class = MyModelSerializer - - def get_queryset(self): - """ - Determine the queryset dynamically, depending on the - user making the request. - - Note that overriding this method follows on more obviously now - that an explicit `queryset` attribute is the usual view style. - """ - return self.user.accounts - -## Django 1.3 support - -The 2.3.x release series will be the last series to provide compatibility with Django 1.3. - -## Version 2.2 API changes - -All API changes in 2.2 that previously raised `PendingDeprecationWarning` will now raise a `DeprecationWarning`, which is loud by default. - -## What comes next? - -* Support for read-write nested serializers is almost complete, and due to be released in the next few weeks. -* Extra filter backends for searching and ordering of results are planned to be added shortly. - -The next few months should see a renewed focus on addressing outstanding tickets. The 2.4 release is currently planned for around August-September. - -[viewset]: ../api-guide/viewsets.md -[router]: ../api-guide/routers.md -[part-6]: ../tutorial/6-viewsets-and-routers.md diff --git a/docs/topics/2.4-announcement.md b/docs/topics/2.4-announcement.md deleted file mode 100644 index 3009daa49b..0000000000 --- a/docs/topics/2.4-announcement.md +++ /dev/null @@ -1,172 +0,0 @@ -# Django REST framework 2.4 - -The 2.4 release is largely an intermediate step, tying up some outstanding issues prior to the 3.x series. - -## Version requirements - -Support for Django 1.3 has been dropped. -The lowest supported version of Django is now 1.4.2. - -The current plan is for REST framework to remain in lockstep with [Django's long-term support policy][lts-releases]. - -## Django 1.7 support - -The optional authtoken application now includes support for *both* Django 1.7 schema migrations, *and* for old-style `south` migrations. - -**If you are using authtoken, and you want to continue using `south`, you must upgrade your `south` package to version 1.0.** - -## Deprecation of `.model` view attribute - -The `.model` attribute on view classes is an optional shortcut for either or both of `.serializer_class` and `.queryset`. Its usage results in more implicit, less obvious behavior. - -The documentation has previously stated that usage of the more explicit style is prefered, and we're now taking that one step further and deprecating the usage of the `.model` shortcut. - -Doing so will mean that there are cases of API code where you'll now need to include a serializer class where you previously were just using the `.model` shortcut. However we firmly believe that it is the right trade-off to make. - -Removing the shortcut takes away an unnecessary layer of abstraction, and makes your codebase more explicit without any significant extra complexity. It also results in better consistency, as there's now only one way to set the serializer class and queryset attributes for the view, instead of two. - -The `DEFAULT_MODEL_SERIALIZER_CLASS` API setting is now also deprecated. - -## Updated test runner - -We now have a new test runner for developing against the project,, that uses the excellent [py.test](http://pytest.org) library. - -To use it make sure you have first installed the test requirements. - - pip install -r requirements-test.txt - -Then run the `runtests.py` script. - - ./runtests.py - -The new test runner also includes [flake8](https://flake8.readthedocs.io) code linting, which should help keep our coding style consistent. - -#### Test runner flags - -Run using a more concise output style. - - ./runtests -q - -Run the tests using a more concise output style, no coverage, no flake8. - - ./runtests --fast - -Don't run the flake8 code linting. - - ./runtests --nolint - -Only run the flake8 code linting, don't run the tests. - - ./runtests --lintonly - -Run the tests for a given test case. - - ./runtests MyTestCase - -Run the tests for a given test method. - - ./runtests MyTestCase.test_this_method - -Shorter form to run the tests for a given test method. - - ./runtests 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. - -## Improved viewset routing - -The `@action` and `@link` decorators were inflexible in that they only allowed additional routes to be added against instance style URLs, not against list style URLs. - -The `@action` and `@link` decorators have now been moved to pending deprecation, and the `@list_route` and `@detail_route` decorators have been introduced. - -Here's an example of using the new decorators. Firstly we have a detail-type route named "set_password" that acts on a single instance, and takes a `pk` argument in the URL. Secondly we have a list-type route named "recent_users" that acts on a queryset, and does not take any arguments in the URL. - - class UserViewSet(viewsets.ModelViewSet): - """ - A viewset that provides the standard actions - """ - queryset = User.objects.all() - serializer_class = UserSerializer - - @detail_route(methods=['post']) - def set_password(self, request, pk=None): - user = self.get_object() - serializer = PasswordSerializer(data=request.DATA) - if serializer.is_valid(): - user.set_password(serializer.data['password']) - user.save() - return Response({'status': 'password set'}) - else: - return Response(serializer.errors, - status=status.HTTP_400_BAD_REQUEST) - - @list_route() - def recent_users(self, request): - recent_users = User.objects.all().order('-last_login') - page = self.paginate_queryset(recent_users) - serializer = self.get_pagination_serializer(page) - return Response(serializer.data) - -For more details, see the [viewsets documentation](../api-guide/viewsets.md). - -## Throttle behavior - -There's one bugfix in 2.4 that's worth calling out, as it will *invalidate existing throttle caches* when you upgrade. - -We've now fixed a typo on the `cache_format` attribute. Previously this was named `"throtte_%(scope)s_%(ident)s"`, it is now `"throttle_%(scope)s_%(ident)s"`. - -If you're concerned about the invalidation you have two options. - -* Manually pre-populate your cache with the fixed version. -* Set the `cache_format` attribute on your throttle class in order to retain the previous incorrect spelling. - -## Other features - -There are also a number of other features and bugfixes as [listed in the release notes][2-4-release-notes]. In particular these include: - -[Customizable view name and description functions][view-name-and-description-settings] for use with the browsable API, by using the `VIEW_NAME_FUNCTION` and `VIEW_DESCRIPTION_FUNCTION` settings. - -Smarter [client IP identification for throttling][client-ip-identification], with the addition of the `NUM_PROXIES` setting. - -Added the standardized `Retry-After` header to throttled responses, as per [RFC 6585](http://tools.ietf.org/html/rfc6585). This should now be used in preference to the custom `X-Throttle-Wait-Seconds` header which will be fully deprecated in 3.0. - -## Deprecations - -All API changes in 2.3 that previously raised `PendingDeprecationWarning` will now raise a `DeprecationWarning`, which is loud by default. - -All API changes in 2.3 that previously raised `DeprecationWarning` have now been removed entirely. - -Furter details on these deprecations is available in the [2.3 announcement][2-3-announcement]. - -## Labels and milestones - -Although not strictly part of the 2.4 release it's also worth noting here that we've been working hard towards improving our triage process. - -The [labels that we use in GitHub][github-labels] have been cleaned up, and all existing tickets triaged. Any given ticket should have one and only one label, indicating its current state. - -We've also [started using milestones][github-milestones] in order to track tickets against particular releases. - ---- - -![Labels and milestones](../img/labels-and-milestones.png) - -**Above**: *Overview of our current use of labels and milestones in GitHub.* - ---- - -We hope both of these changes will help make the management process more clear and obvious and help keep tickets well-organised and relevant. - -## Next steps - -The next planned release will be 3.0, featuring an improved and simplified serializer implementation. - -Once again, many thanks to all the generous [backers and sponsors][kickstarter-sponsors] who've helped make this possible! - -[lts-releases]: https://docs.djangoproject.com/en/dev/internals/release-process/#long-term-support-lts-releases -[2-4-release-notes]: release-notes#240 -[view-name-and-description-settings]: ../api-guide/settings#view-names-and-descriptions -[client-ip-identification]: ../api-guide/throttling#how-clients-are-identified -[2-3-announcement]: 2.3-announcement -[github-labels]: https://github.com/tomchristie/django-rest-framework/issues -[github-milestones]: https://github.com/tomchristie/django-rest-framework/milestones -[kickstarter-sponsors]: kickstarter-announcement#sponsors diff --git a/docs/topics/ajax-csrf-cors.md b/docs/topics/ajax-csrf-cors.md index ad88810da3..646f3f5638 100644 --- a/docs/topics/ajax-csrf-cors.md +++ b/docs/topics/ajax-csrf-cors.md @@ -33,9 +33,9 @@ The best way to deal with CORS in REST framework is to add the required response [Otto Yiu][ottoyiu] maintains the [django-cors-headers] package, which is known to work correctly with REST framework APIs. -[cite]: http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html +[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/dev/ref/csrf/#ajax -[cors]: http://www.w3.org/TR/cors/ +[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/ diff --git a/docs/topics/api-clients.md b/docs/topics/api-clients.md index c12551aa62..3fd5606342 100644 --- a/docs/topics/api-clients.md +++ b/docs/topics/api-clients.md @@ -217,7 +217,7 @@ credentials, headers and bookmarks: # Python client library -The `coreapi` Python package allows you to programatically interact with any +The `coreapi` Python package allows you to programmatically interact with any API that exposes a supported schema format. ## Getting started @@ -240,9 +240,59 @@ Once we have a `Client` instance, we can fetch an API schema from the network. schema = client.get('https://api.example.org/') The object returned from this call will be a `Document` instance, which is -the internal representation of the interface that we are interacting with. +a representation of the API schema. -Now that we have our schema `Document`, we can now start to interact with the API: +## Authentication + +Typically you'll also want to provide some authentication credentials when +instantiating the client. + +#### Token authentication + +The `TokenAuthentication` class can be used to support REST framework's built-in +`TokenAuthentication`, as well as OAuth and JWT schemes. + + auth = coreapi.auth.TokenAuthentication( + scheme='JWT', + token='' + ) + client = coreapi.Client(auth=auth) + +When using TokenAuthentication you'll probably need to implement a login flow +using the CoreAPI client. + +A suggested pattern for this would be to initially make an unauthenticated client +request to an "obtain token" endpoint + +For example, using the "Django REST framework JWT" package + + client = coreapi.Client() + schema = client.get('https://api.example.org/') + + action = ['api-token-auth', 'create'] + params = {"username": "example", "password": "secret"} + result = client.action(schema, action, params) + + auth = coreapi.auth.TokenAuthentication( + scheme='JWT', + token=result['token'] + ) + client = coreapi.Client(auth=auth) + +#### Basic authentication + +The `BasicAuthentication` class can be used to support HTTP Basic Authentication. + + auth = coreapi.auth.BasicAuthentication( + username='', + password='' + ) + client = coreapi.Client(auth=auth) + +## Interacting with the API + +Now that we have a client and have fetched our schema `Document`, we can now +start to interact with the API: users = client.action(schema, ['users', 'list']) @@ -304,7 +354,7 @@ other protocols can also be supported. #### Configuring transports -The behaviour of the network layer can be customized by configuring the +The behavior of the network layer can be customized by configuring the transports that the client is instantiated with. import requests @@ -318,8 +368,160 @@ More complex customizations can also be achieved, for example modifying the underlying `requests.Session` instance to [attach transport adaptors][transport-adaptors] that modify the outgoing requests. +--- + +# JavaScript Client Library + +The JavaScript client library allows you to interact with your API either from a browser, or using node. + +## Installing the JavaScript client + +There are two separate JavaScript resources that you need to include in your HTML pages in order to use the JavaScript client library. These are a static `coreapi.js` file, which contains the code for the dynamic client library, and a templated `schema.js` resource, which exposes your API schema. + +First, install the API documentation views. These will include the schema resource that'll allow you to load the schema directly from an HTML page, without having to make an asynchronous AJAX call. + + from rest_framework.documentation import include_docs_urls + + urlpatterns = [ + ... + url(r'^docs/', include_docs_urls(title='My API service')) + ] + +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. + + + {% load static %} + + + +The `coreapi` library, and the `schema` object will now both be available on the `window` instance. + + 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() + +Typically you'll also want to provide some authentication credentials when +instantiating the client. + +#### Session authentication + +The `SessionAuthentication` class allows session cookies to provide the user +authentication. You'll want to provide a standard HTML login flow, to allow +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}) + +The authentication scheme will handle including a CSRF header in any outgoing +requests for unsafe HTTP methods. + +#### Token authentication + +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}) + +When using TokenAuthentication you'll probably need to implement a login flow +using the CoreAPI client. + +A suggested pattern for this would be to initially make an unauthenticated client +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 + + function loginUser(username, password) { + let action = ["api-token-auth", "obtain-token"] + let params = {username: "example", email: "example@example.com"} + 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'] + }) + window.client = coreapi.Client({auth: auth}) + window.loggedIn = true + }).catch(function (error) { + // Handle error case where eg. user provides incorrect credentials. + }) + } + +#### Basic authentication + +The `BasicAuthentication` class can be used to support HTTP Basic Authentication. + + let auth = new coreapi.auth.BasicAuthentication({ + username: '', + password: '' + }) + let client = new coreapi.Client({auth: auth}) + +## Using the client + +Making requests: + + 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"} + client.action(schema, action, params).then(function(result) { + // Return value is in 'result' + }) + +Handling errors: + + client.action(schema, action, params).then(function(result) { + // Return value is in 'result' + }).catch(function (error) { + // Error value is in 'error' + }) + +## Installation with node + +The coreapi package is available on NPM. + + $ npm install coreapi + $ node + const coreapi = require('coreapi') + +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 + client.get("https://api.example.org/").then(function(data) { + // Load a CoreJSON API schema. + schema = data + console.log('schema loaded') + }) + [heroku-api]: https://devcenter.heroku.com/categories/platform-api -[heroku-example]: http://www.coreapi.org/tools-and-resources/example-services/#heroku-json-hyper-schema -[core-api]: http://www.coreapi.org/ +[heroku-example]: https://www.coreapi.org/tools-and-resources/example-services/#heroku-json-hyper-schema +[core-api]: https://www.coreapi.org/ [schema-generation]: ../api-guide/schemas.md [transport-adaptors]: http://docs.python-requests.org/en/master/user/advanced/#transport-adapters diff --git a/docs/topics/browsable-api.md b/docs/topics/browsable-api.md index bc1431cfc7..ed70c49018 100644 --- a/docs/topics/browsable-api.md +++ b/docs/topics/browsable-api.md @@ -44,7 +44,7 @@ Full example: {% extends "rest_framework/base.html" %} {% block bootstrap_theme %} - + {% endblock %} {% block bootstrap_navbar_variant %}{% endblock %} @@ -94,6 +94,8 @@ To add branding and customize the look-and-feel of the login template, create a You can add your site name or branding by including the branding block: + {% extends "rest_framework/login_base.html" %} + {% block branding %}

My Site Name

{% endblock %} @@ -146,21 +148,17 @@ An alternative, but more complex option would be to replace the input with an au There are [a variety of packages for autocomplete widgets][autocomplete-packages], such as [django-autocomplete-light][django-autocomplete-light], that you may want to refer to. Note that you will not be able to simply include these components as standard widgets, but will need to write the HTML template explicitly. This is because REST framework 3.0 no longer supports the `widget` keyword argument since it now uses templated HTML generation. -Better support for autocomplete inputs is planned in future versions. - --- -[cite]: http://en.wikiquote.org/wiki/Alfred_North_Whitehead +[cite]: https://en.wikiquote.org/wiki/Alfred_North_Whitehead [drfreverse]: ../api-guide/reverse.md [ffjsonview]: https://addons.mozilla.org/en-US/firefox/addon/jsonview/ [chromejsonview]: https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc -[bootstrap]: http://getbootstrap.com +[bootstrap]: https://getbootstrap.com/ [cerulean]: ../img/cerulean.png [slate]: ../img/slate.png -[bcustomize]: http://getbootstrap.com/2.3.2/customize.html -[bswatch]: http://bootswatch.com/ -[bcomponents]: http://getbootstrap.com/2.3.2/components.html -[bcomponentsnav]: http://getbootstrap.com/2.3.2/components.html#navbar +[bswatch]: https://bootswatch.com/ +[bcomponents]: https://getbootstrap.com/2.3.2/components.html +[bcomponentsnav]: https://getbootstrap.com/2.3.2/components.html#navbar [autocomplete-packages]: https://www.djangopackages.com/grids/g/auto-complete/ [django-autocomplete-light]: https://github.com/yourlabs/django-autocomplete-light -[django-autocomplete-light-install]: https://django-autocomplete-light.readthedocs.io/en/master/install.html diff --git a/docs/topics/browser-enhancements.md b/docs/topics/browser-enhancements.md index e1977e826c..67c1c1898f 100644 --- a/docs/topics/browser-enhancements.md +++ b/docs/topics/browser-enhancements.md @@ -50,14 +50,16 @@ Prior to version 3.3.0 the semi extension header `X-HTTP-Method-Override` was su 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 @@ -80,8 +82,8 @@ was later [dropped from the spec][html5]. There remains [ongoing discussion][put_delete] about adding support for `PUT` and `DELETE`, as well as how to support content types other than form-encoded data. -[cite]: http://www.amazon.com/Restful-Web-Services-Leonard-Richardson/dp/0596529260 +[cite]: https://www.amazon.com/RESTful-Web-Services-Leonard-Richardson/dp/0596529260 [ajax-form]: https://github.com/tomchristie/ajax-form -[rails]: http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work -[html5]: http://www.w3.org/TR/html5-diff/#changes-2010-06-24 +[rails]: https://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-put-or-delete-methods-work +[html5]: https://www.w3.org/TR/html5-diff/#changes-2010-06-24 [put_delete]: http://amundsen.com/examples/put-delete-forms/ diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md index e7d2cde0c9..5c806ea7ec 100644 --- a/docs/topics/documenting-your-api.md +++ b/docs/topics/documenting-your-api.md @@ -4,45 +4,139 @@ > > — Roy Fielding, [REST APIs must be hypertext driven][cite] -There are a variety of approaches to API documentation. This document introduces a few of the various tools and options you might choose from. The approaches should not be considered exclusive - you may want to provide more than one documentation style for you API, such as a self describing API that also includes static documentation of the various API endpoints. - -## Endpoint documentation - -The most common way to document Web APIs today is to produce documentation that lists the API endpoints verbatim, and describes the allowable operations on each. There are various tools that allow you to do this in an automated or semi-automated way. - ---- - -#### DRF Docs - -[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] - ---- - -#### 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] +REST framework provides built-in support for generating OpenAPI schemas, which +can be used with tools that allow you to build API documentation. + +There are also a number of great third-party documentation packages available. + +## Generating documentation from OpenAPI schemas + +There are a number of packages available that allow you to generate HTML +documentation pages from OpenAPI schemas. + +Two popular options are [Swagger UI][swagger-ui] and [ReDoc][redoc]. + +Both require little more than the location of your static schema file or +dynamic `SchemaView` endpoint. + +### A minimal example with Swagger UI + +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: + +```html + + + + Swagger + + + + + +
+ + + + +``` + +Save this in your templates folder as `swagger-ui.html`. Then route a +`TemplateView` in your project's URL conf: + +```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'), +] +``` + +See the [Swagger UI documentation][swagger-ui] for advanced usage. + +### A minimal example with ReDoc. + +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: + +```html + + + + ReDoc + + + + + + + + + + + + +``` + +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'), +] +``` + +See the [ReDoc documentation][redoc] for advanced usage. + +## Third party packages + +There are a number of mature third-party packages for providing API documentation. + +#### drf-yasg - Yet Another Swagger Generator + +[drf-yasg][drf-yasg] is a [Swagger][swagger] generation tool implemented without using the schema generation provided +by Django Rest Framework. + +It aims to implement as much of the [OpenAPI][open-api] specification as possible - nested schemas, named models, +response bodies, enum/pattern/min/max validators, form parameters, etc. - and to generate documents usable with code +generation tools like `swagger-codegen`. + +This also translates into a very useful interactive documentation viewer in the form of `swagger-ui`: + + +![Screenshot - drf-yasg][image-drf-yasg] --- @@ -66,7 +160,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): """ @@ -77,7 +171,7 @@ If the python `markdown` library is installed, then [markdown syntax][markdown] [ref]: http://example.com/activating-accounts """ -Note that one constraint of using viewsets is that any documentation be used for all generated views, so for example, you cannot have differing documentation for the generated list view and detail view. +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 @@ -85,16 +179,19 @@ REST framework APIs also support programmatically accessible descriptions, using When using the generic views, any `OPTIONS` requests will additionally respond with metadata regarding any `POST` or `PUT` actions available, describing which fields are on the serializer. -You can modify the response behavior to `OPTIONS` requests by overriding the `metadata` view method. For example: +You can modify the response behavior to `OPTIONS` requests by overriding the `options` view method and/or by providing a custom Metadata class. For example: - def metadata(self, request): + def options(self, request, *args, **kwargs): """ Don't include the view description in OPTIONS responses. """ - data = super(ExampleView, self).metadata(request) + meta = self.metadata_class() + data = meta.determine_metadata(request, self) data.pop('description') return data +See [the Metadata docs][metadata-docs] for more details. + --- ## The hypermedia approach @@ -105,17 +202,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]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven -[drfdocs-repo]: https://github.com/ekonstantinidis/django-rest-framework-docs -[drfdocs-website]: http://www.drfdocs.com/ -[drfdocs-demo]: http://demo.drfdocs.com/ -[django-rest-swagger]: https://github.com/marcgibbons/django-rest-swagger -[swagger]: https://developers.helloreverb.com/swagger/ -[rest-framework-docs]: https://github.com/marcgibbons/django-rest-framework-docs -[apiary]: http://apiary.io/ -[markdown]: http://daringfireball.net/projects/markdown/ +[cite]: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven + [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/ +[schemas-examples]: ../api-guide/schemas/#examples + +[image-drf-yasg]: ../img/drf-yasg.png [image-self-describing-api]: ../img/self-describing.png + +[drf-yasg]: https://github.com/axnsan12/drf-yasg/ +[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/funding.md b/docs/topics/funding.md deleted file mode 100644 index 814de0a3cc..0000000000 --- a/docs/topics/funding.md +++ /dev/null @@ -1,359 +0,0 @@ - - - - -# Funding - -> As a direct result of [a successful Mozilla grant application](mozilla-grant.md), I will be leaving my current role at [DabApps](http://www.dabapps.com), and attempting to secure a sustainable business model for REST framework development. I need your help in order to make this work. -> -> — Tom Christie - -If you use REST framework commercially we strongly encourage you to invest in its continued development by signing up for a paid plan. - -**We believe that collaboratively funded software can offer outstanding returns on investment, by encouraging our users to collectively share the cost of development.** - -Signing up for a paid plan will: - -* Directly contribute to faster releases, more features, and higher quality software. -* Allow more time to be invested in documentation, issue triage, and community support. -* Safeguard the future development of REST framework. - -REST framework continues to be open-source and permissively licensed, but we firmly believe it is in the commercial best-interest for users of the project to invest in its ongoing development. - ---- - -## Making the business case - -Our [successful Kickstarter campaign](https://www.kickstarter.com/projects/tomchristie/django-rest-framework-3) demonstrates the impressive cost-reward ratio of shared funding of open-source software. - -With *typical corporate fundings of just £100-£1000 per organization* we successfully delivered: - -* The comprehensive serializer redesign, and **version 3.0 release**. -* Ongoing triage and community support, **closing over 1600 tickets**. -* Substantial improvements to the Browsable API. -* The admin interface. -* A new pagination API including offset/limit and cursor pagination implementations, plus on-page controls. -* A versioning API, including URL-based and header-based versioning schemes. -* Support for customizable exception handling. -* Support for Django's PostgreSQL HStoreField, ArrayField and JSONField. -* Templated HTML form support, including HTML forms with nested list and objects. -* Internationalization support for API responses, currently with 27 languages. -* The metadata APIs for handling `OPTIONS` requests and schema endpoints. -* Numerous minor improvements and better quality throughout the codebase. - -This incredible level of return on investment is *only possible through collaboratively funded models*, which is why we believe that supporting our paid plans is in everyone's best interest. - -Sign up for a paid plan today, and help ensure that REST framework becomes a sustainable, full-time funded project. - ---- - -## Freelancer plan - -This subscription is recommended for freelancers and other individuals with an interest in seeing REST framework continue to improve. - -If you are using REST framework as an full-time employee, consider recommending that your company takes out a [corporate plan](#corporate-plans). - -
-
-
-
- {{ symbol }} - {{ rates.personal1 }} - /month{% if vat %} +VAT{% endif %} -
-
Freelancer
-
-
- Support ongoing development -
-
- Credited on the site -
-
- - - -
-
-
-
- -*Billing is monthly and you can cancel at any time.* - ---- - -## Corporate plans - -These subscriptions are recommended for companies and organizations using REST framework either publicly or privately. - -In exchange for funding you'll also receive advertising space on our site, allowing you to **promote your company or product to many tens of thousands of developers worldwide**. - -Our professional and premium plans also include **priority support**. At any time your engineers can escalate an issue or discussion group thread, and we'll ensure it gets a guaranteed response within the next working day. - -
-
-
-
- {{ symbol }} - {{ rates.corporate1 }} - /month{% if vat %} +VAT{% endif %} -
-
Basic
-
-
- Support ongoing development -
-
- Funding page ad placement -
-
- -
-
-
-
-
- {{ symbol }} - {{ rates.corporate2 }} - /month{% if vat %} +VAT{% endif %} -
-
Professional
-
-
- Support ongoing development -
-
- Sidebar ad placement -
-
- Priority support for your engineers -
-
- -
-
-
-
-
- {{ symbol }} - {{ rates.corporate3 }} - /month{% if vat %} +VAT{% endif %} -
-
Premium
-
-
- Support ongoing development -
-
- Homepage ad placement -
-
- Sidebar ad placement -
-
- Priority support for your engineers -
-
- -
-
-
- -
- -*Billing is monthly and you can cancel at any time.* - -Once you've signed up I'll contact you via email and arrange your ad placements on the site. - -For further enquires please contact tom@tomchristie.com. - ---- - -## Accountability - -In order to ensure that I can be fully focused on trying to secure a sustainable -& well-funded open source business I will be leaving my current role at [DabApps](http://www.dabapps.com) -at the end of May 2016. - -I have formed a UK limited company, [Encode](http://www.encode.io), which will -act as the business entity behind REST framework. I will be issuing monthly reports -from Encode on progress both towards the [Mozilla grant](mozilla-grant.md), and for development time -funded via the REST framework paid plans. - - - - -
-
-
-

Stay up to date, with our monthly progress reports...

-
- - -
-
- - -
- -
-
-
-
- - - ---- - -## Our sponsors - -
- - diff --git a/docs/topics/html-and-forms.md b/docs/topics/html-and-forms.md index f77ae3af79..18774926b5 100644 --- a/docs/topics/html-and-forms.md +++ b/docs/topics/html-and-forms.md @@ -1,10 +1,10 @@ # HTML & Forms -REST framework is suitable for returning both API style responses, and regular HTML pages. Additionally, serializers can used as HTML forms and rendered in templates. +REST framework is suitable for returning both API style responses, and regular HTML pages. Additionally, serializers can be used as HTML forms and rendered in templates. ## Rendering HTML -In order to return HTML responses you'll need to either `TemplateHTMLRenderer`, or `StaticHTMLRenderer`. +In order to return HTML responses you'll need to use either `TemplateHTMLRenderer`, or `StaticHTMLRenderer`. The `TemplateHTMLRenderer` class expects the response to contain a dictionary of context data, and renders an HTML page based on a template that must be specified either in the view or on the response. @@ -40,7 +40,7 @@ Here's an example of a view that returns a list of "Profile" instances, rendered {% endfor %} - + ## Rendering Forms Serializers may be rendered as forms by using the `render_form` template tag, and including the serializer instance as context to the template. @@ -77,7 +77,7 @@ The following view demonstrates an example of using a serializer in a template f {% load rest_framework %} - +

Profile - {{ profile.name }}

diff --git a/docs/topics/internationalization.md b/docs/topics/internationalization.md index 3968e23d14..7cfc6e247c 100644 --- a/docs/topics/internationalization.md +++ b/docs/topics/internationalization.md @@ -43,7 +43,7 @@ REST framework includes these built-in translations both for standard exception Note that the translations only apply to the error strings themselves. The format of error messages, and the keys of field names will remain the same. An example `400 Bad Request` response body might look like this: - {"detail": {"username": ["Esse campo deve ser unico."]}} + {"detail": {"username": ["Esse campo deve ser único."]}} If you want to use different string for parts of the response such as `detail` and `non_field_errors` then you can modify this behavior by using a [custom exception handler][custom-exception-handler]. @@ -81,7 +81,7 @@ If you're translating a new language you'll need to translate the existing REST 4. Edit the `django.po` file you've just copied, translating all the error messages. -5. Run `manage.py compilemessages -l pt_BR` to make the translations +5. Run `manage.py compilemessages -l pt_BR` to make the translations available for Django to use. You should see a message like `processing file django.po in <...>/locale/pt_BR/LC_MESSAGES`. 6. Restart your development server to see the changes take effect. @@ -102,12 +102,11 @@ 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]: http://youtu.be/Wa0VfS2q94Y +[cite]: https://youtu.be/Wa0VfS2q94Y [django-translation]: https://docs.djangoproject.com/en/1.7/topics/i18n/translation -[custom-exception-handler]: ../api-guide/exceptions.md#custom-exception-handling +[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/tomchristie/django-rest-framework/master/rest_framework/locale/en_US/LC_MESSAGES/django.po +[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 -[contributing]: ../../CONTRIBUTING.md diff --git a/docs/topics/release-notes.md b/docs/topics/release-notes.md deleted file mode 100644 index e5683360b6..0000000000 --- a/docs/topics/release-notes.md +++ /dev/null @@ -1,1218 +0,0 @@ -# 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. - -Medium version numbers (0.x.0) may include API changes, in line with the [deprecation policy][deprecation-policy]. You should read the release notes carefully before upgrading between medium point releases. - -Major version numbers (x.0.0) are reserved for substantial project milestones. - -## Deprecation policy - -REST framework releases follow a formal deprecation policy, which is in line with [Django's deprecation policy][django-deprecation-policy]. - -The timeline for deprecation of a feature present in version 1.0 would work as follows: - -* Version 1.1 would remain **fully backwards compatible** with 1.0, but would raise `PendingDeprecationWarning` warnings if you use the feature that are due to be deprecated. These warnings are **silent by default**, but can be explicitly enabled when you're ready to start migrating any required changes. For example if you start running your tests using `python -Wd manage.py test`, you'll be warned of any API changes you need to make. - -* Version 1.2 would escalate these warnings to `DeprecationWarning`, which is loud by default. - -* Version 1.3 would remove the deprecated bits of API entirely. - -Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change. - -## Upgrading - -To upgrade Django REST framework to the latest version, use pip: - - pip install -U djangorestframework - -You can determine your currently installed version using `pip freeze`: - - pip freeze | grep djangorestframework - ---- - -## 3.5.x series - -### 3.5.3 - -**Date**: [7th November 2016][3.5.3-milestone] - -* Don't raise incorrect FilterSet deprecation warnings. ([#4660][gh4660], [#4643][gh4643], [#4644][gh4644]) -* Schema generation should not raise 404 when a view permission class does. ([#4645][gh4645], [#4646][gh4646]) -* Add `autofocus` support for input controls. ([#4650][gh4650]) - -### 3.5.2 - -**Date**: [1st November 2016][3.5.2-milestone] - -* Restore exception tracebacks in Python 2.7. ([#4631][gh4631], [#4638][gh4638]) -* Properly display dicts in the admin console. ([#4532][gh4532], [#4636][gh4636]) -* Fix is_simple_callable with variable args, kwargs. ([#4622][gh4622], [#4602][gh4602]) -* Support 'on'/'off' literals with BooleanField. ([#4640][gh4640], [#4624][gh4624]) -* Enable cursor pagination of value querysets. ([#4569][gh4569]) -* Fix support of get_full_details() for Throttled exceptions. ([#4627][gh4627]) -* Fix FilterSet proxy. ([#4620][gh4620]) -* Make serializer fields import explicit. ([#4628][gh4628]) -* Drop redundant requests adapter. ([#4639][gh4639]) - -### 3.5.1 - -**Date**: [21st October 2016][3.5.1-milestone] - -* Make `rest_framework/compat.py` imports. ([#4612][gh4612], [#4608][gh4608], [#4601][gh4601]) -* Fix bug in schema base path generation. ([#4611][gh4611], [#4605][gh4605]) -* Fix broken case of ListSerializer with single item. ([#4609][gh4609], [#4606][gh4606]) -* Remove bare `raise` for Python 3.5 compat. ([#4600][gh4600]) - -### 3.5.0 - -**Date**: [20th October 2016][3.5.0-milestone] - ---- - -## 3.4.x series - -### 3.4.7 - -**Date**: [21st September 2016][3.4.7-milestone] - -* Fallback behavior for request parsing when request.POST already accessed. ([#3951][gh3951], [#4500][gh4500]) -* Fix regression of `RegexField`. ([#4489][gh4489], [#4490][gh4490], [#2617][gh2617]) -* Missing comma in `admin.html` causing CSRF error. ([#4472][gh4472], [#4473][gh4473]) -* Fix response rendering with empty context. ([#4495][gh4495]) -* Fix indentation regression in API listing. ([#4493][gh4493]) -* Fixed an issue where the incorrect value is set to `ResolverMatch.func_name` of api_view decorated view. ([#4465][gh4465], [#4462][gh4462]) -* Fix `APIClient.get()` when path contains unicode arguments ([#4458][gh4458]) - -### 3.4.6 - -**Date**: [23rd August 2016][3.4.6-milestone] - -* Fix malformed Javascript in browsable API. ([#4435][gh4435]) -* Skip HiddenField from Schema fields. ([#4425][gh4425], [#4429][gh4429]) -* Improve Create to show the original exception traceback. ([#3508][gh3508]) -* Fix `AdminRenderer` display of PK only related fields. ([#4419][gh4419], [#4423][gh4423]) - -### 3.4.5 - -**Date**: [19th August 2016][3.4.5-milestone] - -* Improve debug error handling. ([#4416][gh4416], [#4409][gh4409]) -* Allow custom CSRF_HEADER_NAME setting. ([#4415][gh4415], [#4410][gh4410]) -* Include .action attribute on viewsets when generating schemas. ([#4408][gh4408], [#4398][gh4398]) -* Do not include request.FILES items in request.POST. ([#4407][gh4407]) -* Fix rendering of checkbox multiple. ([#4403][gh4403]) -* Fix docstring of Field.get_default. ([#4404][gh4404]) -* Replace utf8 character with its ascii counterpart in README. ([#4412][gh4412]) - -### 3.4.4 - -**Date**: [12th August 2016][3.4.4-milestone] - -* Ensure views are fully initialized when generating schemas. ([#4373][gh4373], [#4382][gh4382], [#4383][gh4383], [#4279][gh4279], [#4278][gh4278]) -* Add form field descriptions to schemas. ([#4387][gh4387]) -* Fix category generation for schema endpoints. ([#4391][gh4391], [#4394][gh4394], [#4390][gh4390], [#4386][gh4386], [#4376][gh4376], [#4329][gh4329]) -* Don't strip empty query params when paginating. ([#4392][gh4392], [#4393][gh4393], [#4260][gh4260]) -* Do not re-run query for empty results with LimitOffsetPagination. ([#4201][gh4201], [#4388][gh4388]) -* Stricter type validation for CharField. ([#4380][gh4380], [#3394][gh3394]) -* RelatedField.choices should preserve non-string values. ([#4111][gh4111], [#4379][gh4379], [#3365][gh3365]) -* Test case for rendering checkboxes in vertical form style. ([#4378][gh4378], [#3868][gh3868], [#3868][gh3868]) -* Show error traceback HTML in browsable API ([#4042][gh4042], [#4172][gh4172]) -* Fix handling of ALLOWED_VERSIONS and no DEFAULT_VERSION. [#4370][gh4370] -* Allow `max_digits=None` on DecimalField. ([#4377][gh4377], [#4372][gh4372]) -* Limit queryset when rendering relational choices. ([#4375][gh4375], [#4122][gh4122], [#3329][gh3329], [#3330][gh3330], [#3877][gh3877]) -* Resolve form display with ChoiceField, MultipleChoiceField and non-string choices. ([#4374][gh4374], [#4119][gh4119], [#4121][gh4121], [#4137][gh4137], [#4120][gh4120]) -* Fix call to TemplateHTMLRenderer.resolve_context() fallback method. ([#4371][gh4371]) - -### 3.4.3 - -**Date**: [5th August 2016][3.4.3-milestone] - -* Include fallaback for users of older TemplateHTMLRenderer internal API. ([#4361][gh4361]) - -### 3.4.2 - -**Date**: [5th August 2016][3.4.2-milestone] - -* Include kwargs passed to 'as_view' when generating schemas. ([#4359][gh4359], [#4330][gh4330], [#4331][gh4331]) -* Access `request.user.is_authenticated` as property not method, under Django 1.10+ ([#4358][gh4358], [#4354][gh4354]) -* Filter HEAD out from schemas. ([#4357][gh4357]) -* extra_kwargs takes precedence over uniqueness kwargs. ([#4198][gh4198], [#4199][gh4199], [#4349][gh4349]) -* Correct descriptions when tabs are used in code indentation. ([#4345][gh4345], [#4347][gh4347])* -* Change template context generation in TemplateHTMLRenderer. ([#4236][gh4236]) -* Serializer defaults should not be included in partial updates. ([#4346][gh4346], [#3565][gh3565]) -* Consistent behavior & descriptive error from FileUploadParser when filename not included. ([#4340][gh4340], [#3610][gh3610], [#4292][gh4292], [#4296][gh4296]) -* DecimalField quantizes incoming digitals. ([#4339][gh4339], [#4318][gh4318]) -* Handle non-string input for IP fields. ([#4335][gh4335], [#4336][gh4336], [#4338][gh4338]) -* Fix leading slash handling when Schema generation includes a root URL. ([#4332][gh4332]) -* Test cases for DictField with allow_null options. ([#4348][gh4348]) -* Update tests from Django 1.10 beta to Django 1.10. ([#4344][gh4344]) - -### 3.4.1 - -**Date**: [28th July 2016][3.4.1-milestone] - -* Added `root_renderers` argument to `DefaultRouter`. ([#4323][gh4323], [#4268][gh4268]) -* Added `url` and `schema_url` arguments. ([#4321][gh4321], [#4308][gh4308], [#4305][gh4305]) -* Unique together checks should apply to read-only fields which have a default. ([#4316][gh4316], [#4294][gh4294]) -* Set view.format_kwarg in schema generator. ([#4293][gh4293], [#4315][gh4315]) -* Fix schema generator for views with `pagination_class = None`. ([#4314][gh4314], [#4289][gh4289]) -* Fix schema generator for views with no `get_serializer_class`. ([#4265][gh4265], [#4285][gh4285]) -* Fixes for media type parameters in `Accept` and `Content-Type` headers. ([#4287][gh4287], [#4313][gh4313], [#4281][gh4281]) -* Use verbose_name instead of object_name in error messages. ([#4299][gh4299]) -* Minor version update to Twitter Bootstrap. ([#4307][gh4307]) -* SearchFilter raises error when using with related field. ([#4302][gh4302], [#4303][gh4303], [#4298][gh4298]) -* Adding support for RFC 4918 status codes. ([#4291][gh4291]) -* Add LICENSE.md to the built wheel. ([#4270][gh4270]) -* Serializing "complex" field returns None instead of the value since 3.4 ([#4272][gh4272], [#4273][gh4273], [#4288][gh4288]) - -### 3.4.0 - -**Date**: [14th July 2016][3.4.0-milestone] - -* Don't strip microseconds in JSON output. ([#4256][gh4256]) -* Two slightly different iso 8601 datetime serialization. ([#4255][gh4255]) -* Resolve incorrect inclusion of media type parameters. ([#4254][gh4254]) -* Response Content-Type potentially malformed. ([#4253][gh4253]) -* Fix setup.py error on some platforms. ([#4246][gh4246]) -* Move alternate formats in coreapi into separate packages. ([#4244][gh4244]) -* Add localize keyword argument to `DecimalField`. ([#4233][gh4233]) -* Fix issues with routers for custom list-route and detail-routes. ([#4229][gh4229]) -* Namespace versioning with nested namespaces. ([#4219][gh4219]) -* Robust uniqueness checks. ([#4217][gh4217]) -* Minor refactoring of `must_call_distinct`. ([#4215][gh4215]) -* Overridable offset cutoff in CursorPagination. ([#4212][gh4212]) -* Pass through strings as-in with date/time fields. ([#4196][gh4196]) -* Add test confirming that required=False is valid on a relational field. ([#4195][gh4195]) -* In LimitOffsetPagination `limit=0` should revert to default limit. ([#4194][gh4194]) -* Exclude read_only=True fields from unique_together validation & add docs. ([#4192][gh4192]) -* Handle bytestrings in JSON. ([#4191][gh4191]) -* JSONField(binary=True) represents using binary strings, which JSONRenderer does not support. ([#4187][gh4187]) -* JSONField(binary=True) represents using binary strings, which JSONRenderer does not support. ([#4185][gh4185]) -* More robust form rendering in the browsable API. ([#4181][gh4181]) -* Empty cases of `.validated_data` and `.errors` as lists not dicts for ListSerializer. ([#4180][gh4180]) -* Schemas & client libraries. ([#4179][gh4179]) -* Removed `AUTH_USER_MODEL` compat property. ([#4176][gh4176]) -* Clean up existing deprecation warnings. ([#4166][gh4166]) -* Django 1.10 support. ([#4158][gh4158]) -* Updated jQuery version to 1.12.4. ([#4157][gh4157]) -* More robust default behavior on OrderingFilter. ([#4156][gh4156]) -* description.py codes and tests removal. ([#4153][gh4153]) -* Wrap guardian.VERSION in tuple. ([#4149][gh4149]) -* Refine validator for fields with kwargs. ([#4146][gh4146]) -* Fix None values representation in childs of ListField, DictField. ([#4118][gh4118]) -* Resolve TimeField representation for midnight value. ([#4107][gh4107]) -* Set proper status code in AdminRenderer for the redirection after POST/DELETE requests. ([#4106][gh4106]) -* TimeField render returns None instead of 00:00:00. ([#4105][gh4105]) -* Fix incorrectly named zh-hans and zh-hant locale path. ([#4103][gh4103]) -* Prevent raising exception when limit is 0. ([#4098][gh4098]) -* TokenAuthentication: Allow custom keyword in the header. ([#4097][gh4097]) -* Handle incorrectly padded HTTP basic auth header. ([#4090][gh4090]) -* LimitOffset pagination crashes Browseable API when limit=0. ([#4079][gh4079]) -* Fixed DecimalField arbitrary precision support. ([#4075][gh4075]) -* Added support for custom CSRF cookie names. ([#4049][gh4049]) -* Fix regression introduced by #4035. ([#4041][gh4041]) -* No auth view failing permission should raise 403. ([#4040][gh4040]) -* Fix string_types / text_types confusion. ([#4025][gh4025]) -* Do not list related field choices in OPTIONS requests. ([#4021][gh4021]) -* Fix typo. ([#4008][gh4008]) -* Reorder initializing the view. ([#4006][gh4006]) -* Type error in DjangoObjectPermissionsFilter on Python 3.4. ([#4005][gh4005]) -* Fixed use of deprecated Query.aggregates. ([#4003][gh4003]) -* Fix blank lines around docstrings. ([#4002][gh4002]) -* Fixed admin pagination when limit is 0. ([#3990][gh3990]) -* OrderingFilter adjustements. ([#3983][gh3983]) -* Non-required serializer related fields. ([#3976][gh3976]) -* Using safer calling way of "@api_view" in tutorial. ([#3971][gh3971]) -* ListSerializer doesn't handle unique_together constraints. ([#3970][gh3970]) -* Add missing migration file. ([#3968][gh3968]) -* `OrderingFilter` should call `get_serializer_class()` to determine default fields. ([#3964][gh3964]) -* Remove old django checks from tests and compat. ([#3953][gh3953]) -* Support callable as the value of `initial` for any `serializer.Field`. ([#3943][gh3943]) -* Prevented unnecessary distinct() call in SearchFilter. ([#3938][gh3938]) -* Fix None UUID ForeignKey serialization. ([#3936][gh3936]) -* Drop EOL Django 1.7. ([#3933][gh3933]) -* Add missing space in serializer error message. ([#3926][gh3926]) -* Fixed _force_text_recursive typo. ([#3908][gh3908]) -* Attempt to address Django 2.0 deprecate warnings related to `field.rel`. ([#3906][gh3906]) -* Fix parsing multipart data using a nested serializer with list. ([#3820][gh3820]) -* Resolving APIs URL to different namespaces. ([#3816][gh3816]) -* Do not HTML-escape `help_text` in Browsable API forms. ([#3812][gh3812]) -* OPTIONS fetches and shows all possible foreign keys in choices field. ([#3751][gh3751]) -* Django 1.9 deprecation warnings ([#3729][gh3729]) -* Test case for #3598 ([#3710][gh3710]) -* Adding support for multiple values for search filter. ([#3541][gh3541]) -* Use get_serializer_class in ordering filter. ([#3487][gh3487]) -* Serializers with many=True should return empty list rather than empty dict. ([#3476][gh3476]) -* LimitOffsetPagination limit=0 fix. ([#3444][gh3444]) -* Enable Validators to defer string evaluation and handle new string format. ([#3438][gh3438]) -* Unique validator is executed and breaks if field is invalid. ([#3381][gh3381]) -* Do not ignore overridden View.get_view_name() in breadcrumbs. ([#3273][gh3273]) -* Retry form rendering when rendering with serializer fails. ([#3164][gh3164]) -* Unique constraint prevents nested serializers from updating. ([#2996][gh2996]) -* Uniqueness validators should not be run for excluded (read_only) fields. ([#2848][gh2848]) -* UniqueValidator raises exception for nested objects. ([#2403][gh2403]) -* `lookup_type` is deprecated in favor of `lookup_expr`. ([#4259][gh4259]) ---- - -## 3.3.x series - -### 3.3.3 - -**Date**: [14th March 2016][3.3.3-milestone]. - -* Remove version string from templates. Thanks to @blag for the report and fixes. ([#3878][gh3878], [#3913][gh3913], [#3912][gh3912]) -* Fixes vertical html layout for `BooleanField`. Thanks to Mikalai Radchuk for the fix. ([#3910][gh3910]) -* Silenced deprecation warnings on Django 1.8. Thanks to Simon Charette for the fix. ([#3903][gh3903]) -* Internationalization for authtoken. Thanks to Michael Nacharov for the fix. ([#3887][gh3887], [#3968][gh3968]) -* Fix `Token` model as `abstract` when the authtoken application isn't declared. Thanks to Adam Thomas for the report. ([#3860][gh3860], [#3858][gh3858]) -* Improve Markdown version compatibility. Thanks to Michael J. Schultz for the fix. ([#3604][gh3604], [#3842][gh3842]) -* `QueryParameterVersioning` does not use `DEFAULT_VERSION` setting. Thanks to Brad Montgomery for the fix. ([#3833][gh3833]) -* Add an explicit `on_delete` on the models. Thanks to Mads Jensen for the fix. ([#3832][gh3832]) -* Fix `DateField.to_representation` to work with Python 2 unicode. Thanks to Mikalai Radchuk for the fix. ([#3819][gh3819]) -* Fixed `TimeField` not handling string times. Thanks to Areski Belaid for the fix. ([#3809][gh3809]) -* Avoid updates of `Meta.extra_kwargs`. Thanks to Kevin Massey for the report and fix. ([#3805][gh3805], [#3804][gh3804]) -* Fix nested validation error being rendered incorrectly. Thanks to Craig de Stigter for the fix. ([#3801][gh3801]) -* Document how to avoid CSRF and missing button issues with `django-crispy-forms`. Thanks to Emmanuelle Delescolle, José Padilla and Luis San Pablo for the report, analysis and fix. ([#3787][gh3787], [#3636][gh3636], [#3637][gh3637]) -* Improve Rest Framework Settings file setup time. Thanks to Miles Hutson for the report and Mads Jensen for the fix. ([#3786][gh3786], [#3815][gh3815]) -* Improve authtoken compatibility with Django 1.9. Thanks to S. Andrew Sheppard for the fix. ([#3785][gh3785]) -* Fix `Min/MaxValueValidator` transfer from a model's `DecimalField`. Thanks to Kevin Brown for the fix. ([#3774][gh3774]) -* Improve HTML title in the Browsable API. Thanks to Mike Lissner for the report and fix. ([#3769][gh3769]) -* Fix `AutoFilterSet` to inherit from `default_filter_set`. Thanks to Tom Linford for the fix. ([#3753][gh3753]) -* Fix transifex config to handle the new Chinese language codes. Thanks to @nypisces for the report and fix. ([#3739][gh3739]) -* `DateTimeField` does not handle empty values correctly. Thanks to Mick Parker for the report and fix. ([#3731][gh3731], [#3726][gh3728]) -* Raise error when setting a removed rest_framework setting. Thanks to Luis San Pablo for the fix. ([#3715][gh3715]) -* Add missing csrf_token in AdminRenderer post form. Thanks to Piotr Śniegowski for the fix. ([#3703][gh3703]) -* Refactored `_get_reverse_relationships()` to use correct `to_field`. Thanks to Benjamin Phillips for the fix. ([#3696][gh3696]) -* Document the use of `get_queryset` for `RelatedField`. Thanks to Ryan Hiebert for the fix. ([#3605][gh3605]) -* Fix empty pk detection in HyperlinkRelatedField.get_url. Thanks to @jslang for the fix ([#3962][gh3962]) - -### 3.3.2 - -**Date**: [14th December 2015][3.3.2-milestone]. - -* `ListField` enforces input is a list. ([#3513][gh3513]) -* Fix regression hiding raw data form. ([#3600][gh3600], [#3578][gh3578]) -* Fix Python 3.5 compatibility. ([#3534][gh3534], [#3626][gh3626]) -* Allow setting a custom Django Paginator in `pagination.PageNumberPagination`. ([#3631][gh3631], [#3684][gh3684]) -* Fix relational fields without `to_fields` attribute. ([#3635][gh3635], [#3634][gh3634]) -* Fix `template.render` deprecation warnings for Django 1.9. ([#3654][gh3654]) -* Sort response headers in browsable API renderer. ([#3655][gh3655]) -* Use related_objects api for Django 1.9+. ([#3656][gh3656], [#3252][gh3252]) -* Add confirm modal when deleting. ([#3228][gh3228], [#3662][gh3662]) -* Reveal previously hidden AttributeErrors and TypeErrors while calling has_[object_]permissions. ([#3668][gh3668]) -* Make DRF compatible with multi template engine in Django 1.8. ([#3672][gh3672]) -* Update `NestedBoundField` to also handle empty string when rendering its form. ([#3677][gh3677]) -* Fix UUID validation to properly catch invalid input types. ([#3687][gh3687], [#3679][gh3679]) -* Fix caching issues. ([#3628][gh3628], [#3701][gh3701]) -* Fix Admin and API browser for views without a filter_class. ([#3705][gh3705], [#3596][gh3596], [#3597][gh3597]) -* Add app_name to rest_framework.urls. ([#3714][gh3714]) -* Improve authtoken's views to support url versioning. ([#3718][gh3718], [#3723][gh3723]) - -### 3.3.1 - -**Date**: [4th November 2015][3.3.1-milestone]. - -* Resolve parsing bug when accessing `request.POST` ([#3592][gh3592]) -* Correctly deal with `to_field` referring to primary key. ([#3593][gh3593]) -* Allow filter HTML to render when no `filter_class` is defined. ([#3560][gh3560]) -* Fix admin rendering issues. ([#3564][gh3564], [#3556][gh3556]) -* Fix issue with DecimalValidator. ([#3568][gh3568]) - -### 3.3.0 - -**Date**: [28th October 2015][3.3.0-milestone]. - -* HTML controls for filters. ([#3315][gh3315]) -* Forms API. ([#3475][gh3475]) -* AJAX browsable API. ([#3410][gh3410]) -* Added JSONField. ([#3454][gh3454]) -* Correctly map `to_field` when creating `ModelSerializer` relational fields. ([#3526][gh3526]) -* Include keyword arguments when mapping `FilePathField` to a serializer field. ([#3536][gh3536]) -* Map appropriate model `error_messages` on `ModelSerializer` uniqueness constraints. ([#3435][gh3435]) -* Include `max_length` constraint for `ModelSerializer` fields mapped from TextField. ([#3509][gh3509]) -* Added support for Django 1.9. ([#3450][gh3450], [#3525][gh3525]) -* Removed support for Django 1.5 & 1.6. ([#3421][gh3421], [#3429][gh3429]) -* Removed 'south' migrations. ([#3495][gh3495]) - ---- - -## 3.2.x series - -### 3.2.5 - -**Date**: [27th October 2015][3.2.5-milestone]. - -* Escape `username` in optional logout tag. ([#3550][gh3550]) - -### 3.2.4 - -**Date**: [21th September 2015][3.2.4-milestone]. - -* Don't error on missing `ViewSet.search_fields` attribute. ([#3324][gh3324], [#3323][gh3323]) -* Fix `allow_empty` not working on serializers with `many=True`. ([#3361][gh3361], [#3364][gh3364]) -* Let `DurationField` accepts integers. ([#3359][gh3359]) -* Multi-level dictionaries not supported in multipart requests. ([#3314][gh3314]) -* Fix `ListField` truncation on HTTP PATCH ([#3415][gh3415], [#2761][gh2761]) - -### 3.2.3 - -**Date**: [24th August 2015][3.2.3-milestone]. - -* Added `html_cutoff` and `html_cutoff_text` for limiting select dropdowns. ([#3313][gh3313]) -* Added regex style to `SearchFilter`. ([#3316][gh3316]) -* Resolve issues with setting blank HTML fields. ([#3318][gh3318]) ([#3321][gh3321]) -* Correctly display existing 'select multiple' values in browsable API forms. ([#3290][gh3290]) -* Resolve duplicated validation message for `IPAddressField`. ([#3249[gh3249]) ([#3250][gh3250]) -* Fix to ensure admin renderer continues to work when pagination is disabled. ([#3275][gh3275]) -* Resolve error with `LimitOffsetPagination` when count=0, offset=0. ([#3303][gh3303]) - -### 3.2.2 - -**Date**: [13th August 2015][3.2.2-milestone]. - -* Add `display_value()` method for use when displaying relational field select inputs. ([#3254][gh3254]) -* Fix issue with `BooleanField` checkboxes incorrectly displaying as checked. ([#3258][gh3258]) -* Ensure empty checkboxes properly set `BooleanField` to `False` in all cases. ([#2776][gh2776]) -* Allow `WSGIRequest.FILES` property without raising incorrect deprecated error. ([#3261][gh3261]) -* Resolve issue with rendering nested serializers in forms. ([#3260][gh3260]) -* Raise an error if user accidentally pass a serializer instance to a response, rather than data. ([#3241][gh3241]) - -### 3.2.1 - -**Date**: [7th August 2015][3.2.1-milestone]. - -* Fix for relational select widgets rendering without any choices. ([#3237][gh3237]) -* Fix for `1`, `0` rendering as `true`, `false` in the admin interface. [#3227][gh3227]) -* Fix for ListFields with single value in HTML form input. ([#3238][gh3238]) -* Allow `request.FILES` for compat with Django's `HTTPRequest` class. ([#3239][gh3239]) - -### 3.2.0 - -**Date**: [6th August 2015][3.2.0-milestone]. - -* Add `AdminRenderer`. ([#2926][gh2926]) -* Add `FilePathField`. ([#1854][gh1854]) -* Add `allow_empty` to `ListField`. ([#2250][gh2250]) -* Support django-guardian 1.3. ([#3165][gh3165]) -* Support grouped choices. ([#3225][gh3225]) -* Support error forms in browsable API. ([#3024][gh3024]) -* Allow permission classes to customize the error message. ([#2539][gh2539]) -* Support `source=` on hyperlinked fields. ([#2690][gh2690]) -* `ListField(allow_null=True)` now allows null as the list value, not null items in the list. ([#2766][gh2766]) -* `ManyToMany()` maps to `allow_empty=False`, `ManyToMany(blank=True)` maps to `allow_empty=True`. ([#2804][gh2804]) -* Support custom serialization styles for primary key fields. ([#2789][gh2789]) -* `OPTIONS` requests support nested representations. ([#2915][gh2915]) -* Set `view.action == "metadata"` for viewsets with `OPTIONS` requests. ([#3115][gh3115]) -* Support `allow_blank` on `UUIDField`. ([#3130][gh#3130]) -* Do not display view docstrings with 401 or 403 response codes. ([#3216][gh3216]) -* Resolve Django 1.8 deprecation warnings. ([#2886][gh2886]) -* Fix for `DecimalField` validation. ([#3139][gh3139]) -* Fix behavior of `allow_blank=False` when used with `trim_whitespace=True`. ([#2712][gh2712]) -* Fix issue with some field combinations incorrectly mapping to an invalid `allow_blank` argument. ([#3011][gh3011]) -* Fix for output representations with prefetches and modified querysets. ([#2704][gh2704], [#2727][gh2727]) -* Fix assertion error when CursorPagination is provided with certains invalid query parameters. (#2920)[gh2920]. -* Fix `UnicodeDecodeError` when invalid characters included in header with `TokenAuthentication`. ([#2928][gh2928]) -* Fix transaction rollbacks with `@non_atomic_requests` decorator. ([#3016][gh3016]) -* Fix duplicate results issue with Oracle databases using `SearchFilter`. ([#2935][gh2935]) -* Fix checkbox alignment and rendering in browsable API forms. ([#2783][gh2783]) -* Fix for unsaved file objects which should use `"url": null` in the representation. ([#2759][gh2759]) -* Fix field value rendering in browsable API. ([#2416][gh2416]) -* Fix `HStoreField` to include `allow_blank=True` in `DictField` mapping. ([#2659][gh2659]) -* Numerous other cleanups, improvements to error messaging, private API & minor fixes. - ---- - -## 3.1.x series - -### 3.1.3 - -**Date**: [4th June 2015][3.1.3-milestone]. - -* Add `DurationField`. ([#2481][gh2481], [#2989][gh2989]) -* Add `format` argument to `UUIDField`. ([#2788][gh2788], [#3000][gh3000]) -* `MultipleChoiceField` empties incorrectly on a partial update using multipart/form-data ([#2993][gh2993], [#2894][gh2894]) -* Fix a bug in options related to read-only `RelatedField`. ([#2981][gh2981], [#2811][gh2811]) -* Fix nested serializers with `unique_together` relations. ([#2975][gh2975]) -* Allow unexpected values for `ChoiceField`/`MultipleChoiceField` representations. ([#2839][gh2839], [#2940][gh2940]) -* Rollback the transaction on error if `ATOMIC_REQUESTS` is set. ([#2887][gh2887], [#2034][gh2034]) -* Set the action on a view when override_method regardless of its None-ness. ([#2933][gh2933]) -* `DecimalField` accepts `2E+2` as 200 and validates decimal place correctly. ([#2948][gh2948], [#2947][gh2947]) -* Support basic authentication with custom `UserModel` that change `username`. ([#2952][gh2952]) -* `IPAddressField` improvements. ([#2747][gh2747], [#2618][gh2618], [#3008][gh3008]) -* Improve `DecimalField` for easier subclassing. ([#2695][gh2695]) - - -### 3.1.2 - -**Date**: [13rd May 2015][3.1.2-milestone]. - -* `DateField.to_representation` can handle str and empty values. ([#2656][gh2656], [#2687][gh2687], [#2869][gh2869]) -* Use default reason phrases from HTTP standard. ([#2764][gh2764], [#2763][gh2763]) -* Raise error when `ModelSerializer` used with abstract model. ([#2757][gh2757], [#2630][gh2630]) -* Handle reversal of non-API view_name in `HyperLinkedRelatedField` ([#2724][gh2724], [#2711][gh2711]) -* Dont require pk strictly for related fields. ([#2745][gh2745], [#2754][gh2754]) -* Metadata detects null boolean field type. ([#2762][gh2762]) -* Proper handling of depth in nested serializers. ([#2798][gh2798]) -* Display viewset without paginator. ([#2807][gh2807]) -* Don't check for deprecated `.model` attribute in permissions ([#2818][gh2818]) -* Restrict integer field to integers and strings. ([#2835][gh2835], [#2836][gh2836]) -* Improve `IntegerField` to use compiled decimal regex. ([#2853][gh2853]) -* Prevent empty `queryset` to raise AssertionError. ([#2862][gh2862]) -* `DjangoModelPermissions` rely on `get_queryset`. ([#2863][gh2863]) -* Check `AcceptHeaderVersioning` with content negotiation in place. ([#2868][gh2868]) -* Allow `DjangoObjectPermissions` to use views that define `get_queryset`. ([#2905][gh2905]) - - -### 3.1.1 - -**Date**: [23rd March 2015][3.1.1-milestone]. - -* **Security fix**: Escape tab switching cookie name in browsable API. -* Display input forms in browsable API if `serializer_class` is used, even when `get_serializer` method does not exist on the view. ([#2743][gh2743]) -* Use a password input for the AuthTokenSerializer. ([#2741][gh2741]) -* Fix missing anchor closing tag after next button. ([#2691][gh2691]) -* Fix `lookup_url_kwarg` handling in viewsets. ([#2685][gh2685], [#2591][gh2591]) -* Fix problem with importing `rest_framework.views` in `apps.py` ([#2678][gh2678]) -* LimitOffsetPagination raises `TypeError` if PAGE_SIZE not set ([#2667][gh2667], [#2700][gh2700]) -* German translation for `min_value` field error message references `max_value`. ([#2645][gh2645]) -* Remove `MergeDict`. ([#2640][gh2640]) -* Support serializing unsaved models with related fields. ([#2637][gh2637], [#2641][gh2641]) -* Allow blank/null on radio.html choices. ([#2631][gh2631]) - - -### 3.1.0 - -**Date**: [5th March 2015][3.1.0-milestone]. - -For full details see the [3.1 release announcement](3.1-announcement.md). - ---- - -## 3.0.x series - -### 3.0.5 - -**Date**: [10th February 2015][3.0.5-milestone]. - -* Fix a bug where `_closable_objects` breaks pickling. ([#1850][gh1850], [#2492][gh2492]) -* Allow non-standard `User` models with `Throttling`. ([#2524][gh2524]) -* Support custom `User.db_table` in TokenAuthentication migration. ([#2479][gh2479]) -* Fix misleading `AttributeError` tracebacks on `Request` objects. ([#2530][gh2530], [#2108][gh2108]) -* `ManyRelatedField.get_value` clearing field on partial update. ([#2475][gh2475]) -* Removed '.model' shortcut from code. ([#2486][gh2486]) -* Fix `detail_route` and `list_route` mutable argument. ([#2518][gh2518]) -* Prefetching the user object when getting the token in `TokenAuthentication`. ([#2519][gh2519]) - -### 3.0.4 - -**Date**: [28th January 2015][3.0.4-milestone]. - -* Django 1.8a1 support. ([#2425][gh2425], [#2446][gh2446], [#2441][gh2441]) -* Add `DictField` and support Django 1.8 `HStoreField`. ([#2451][gh2451], [#2106][gh2106]) -* Add `UUIDField` and support Django 1.8 `UUIDField`. ([#2448][gh2448], [#2433][gh2433], [#2432][gh2432]) -* `BaseRenderer.render` now raises `NotImplementedError`. ([#2434][gh2434]) -* Fix timedelta JSON serialization on Python 2.6. ([#2430][gh2430]) -* `ResultDict` and `ResultList` now appear as standard dict/list. ([#2421][gh2421]) -* Fix visible `HiddenField` in the HTML form of the web browsable API page. ([#2410][gh2410]) -* Use `OrderedDict` for `RelatedField.choices`. ([#2408][gh2408]) -* Fix ident format when using `HTTP_X_FORWARDED_FOR`. ([#2401][gh2401]) -* Fix invalid key with memcached while using throttling. ([#2400][gh2400]) -* Fix `FileUploadParser` with version 3.x. ([#2399][gh2399]) -* Fix the serializer inheritance. ([#2388][gh2388]) -* Fix caching issues with `ReturnDict`. ([#2360][gh2360]) - -### 3.0.3 - -**Date**: [8th January 2015][3.0.3-milestone]. - -* Fix `MinValueValidator` on `models.DateField`. ([#2369][gh2369]) -* Fix serializer missing context when pagination is used. ([#2355][gh2355]) -* Namespaced router URLs are now supported by the `DefaultRouter`. ([#2351][gh2351]) -* `required=False` allows omission of value for output. ([#2342][gh2342]) -* Use textarea input for `models.TextField`. ([#2340][gh2340]) -* Use custom `ListSerializer` for pagination if required. ([#2331][gh2331], [#2327][gh2327]) -* Better behavior with null and '' for blank HTML fields. ([#2330][gh2330]) -* Ensure fields in `exclude` are model fields. ([#2319][gh2319]) -* Fix `IntegerField` and `max_length` argument incompatibility. ([#2317][gh2317]) -* Fix the YAML encoder for 3.0 serializers. ([#2315][gh2315], [#2283][gh2283]) -* Fix the behavior of empty HTML fields. ([#2311][gh2311], [#1101][gh1101]) -* Fix Metaclass attribute depth ignoring fields attribute. ([#2287][gh2287]) -* Fix `format_suffix_patterns` to work with Django's `i18n_patterns`. ([#2278][gh2278]) -* Ability to customize router URLs for custom actions, using `url_path`. ([#2010][gh2010]) -* Don't install Django REST Framework as egg. ([#2386][gh2386]) - -### 3.0.2 - -**Date**: [17th December 2014][3.0.2-milestone]. - -* Ensure `request.user` is made available to response middleware. ([#2155][gh2155]) -* `Client.logout()` also cancels any existing `force_authenticate`. ([#2218][gh2218], [#2259][gh2259]) -* Extra assertions and better checks to preventing incorrect serializer API use. ([#2228][gh2228], [#2234][gh2234], [#2262][gh2262], [#2263][gh2263], [#2266][gh2266], [#2267][gh2267], [#2289][gh2289], [#2291][gh2291]) -* Fixed `min_length` message for `CharField`. ([#2255][gh2255]) -* Fix `UnicodeDecodeError`, which can occur on serializer `repr`. ([#2270][gh2270], [#2279][gh2279]) -* Fix empty HTML values when a default is provided. ([#2280][gh2280], [#2294][gh2294]) -* Fix `SlugRelatedField` raising `UnicodeEncodeError` when used as a multiple choice input. ([#2290][gh2290]) - -### 3.0.1 - -**Date**: [11th December 2014][3.0.1-milestone]. - -* More helpful error message when the default Serializer `create()` fails. ([#2013][gh2013]) -* Raise error when attempting to save serializer if data is not valid. ([#2098][gh2098]) -* Fix `FileUploadParser` breaks with empty file names and multiple upload handlers. ([#2109][gh2109]) -* Improve `BindingDict` to support standard dict-functions. ([#2135][gh2135], [#2163][gh2163]) -* Add `validate()` to `ListSerializer`. ([#2168][gh2168], [#2225][gh2225], [#2232][gh2232]) -* Fix JSONP renderer failing to escape some characters. ([#2169][gh2169], [#2195][gh2195]) -* Add missing default style for `FileField`. ([#2172][gh2172]) -* Actions are required when calling `ViewSet.as_view()`. ([#2175][gh2175]) -* Add `allow_blank` to `ChoiceField`. ([#2184][gh2184], [#2239][gh2239]) -* Cosmetic fixes in the HTML renderer. ([#2187][gh2187]) -* Raise error if `fields` on serializer is not a list of strings. ([#2193][gh2193], [#2213][gh2213]) -* Improve checks for nested creates and updates. ([#2194][gh2194], [#2196][gh2196]) -* `validated_attrs` argument renamed to `validated_data` in `Serializer` `create()`/`update()`. ([#2197][gh2197]) -* Remove deprecated code to reflect the dropped Django versions. ([#2200][gh2200]) -* Better serializer errors for nested writes. ([#2202][gh2202], [#2215][gh2215]) -* Fix pagination and custom permissions incompatibility. ([#2205][gh2205]) -* Raise error if `fields` on serializer is not a list of strings. ([#2213][gh2213]) -* Add missing translation markers for relational fields. ([#2231][gh2231]) -* Improve field lookup behavior for dicts/mappings. ([#2244][gh2244], [#2243][gh2243]) -* Optimized hyperlinked PK. ([#2242][gh2242]) - -### 3.0.0 - -**Date**: 1st December 2014 - -For full details see the [3.0 release announcement](3.0-announcement.md). - ---- - -For older release notes, [please see the version 2.x documentation][old-release-notes]. - -[cite]: http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html -[deprecation-policy]: #deprecation-policy -[django-deprecation-policy]: https://docs.djangoproject.com/en/dev/internals/release-process/#internal-release-deprecation-policy -[defusedxml-announce]: http://blog.python.org/2013/02/announcing-defusedxml-fixes-for-xml.html -[743]: https://github.com/tomchristie/django-rest-framework/pull/743 -[staticfiles14]: https://docs.djangoproject.com/en/1.4/howto/static-files/#with-a-template-tag -[staticfiles13]: https://docs.djangoproject.com/en/1.3/howto/static-files/#with-a-template-tag -[2.1.0-notes]: https://groups.google.com/d/topic/django-rest-framework/Vv2M0CMY9bg/discussion -[ticket-582]: https://github.com/tomchristie/django-rest-framework/issues/582 -[rfc-6266]: http://tools.ietf.org/html/rfc6266#section-4.3 -[old-release-notes]: https://github.com/tomchristie/django-rest-framework/blob/version-2.4.x/docs/topics/release-notes.md - -[3.0.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.1+Release%22 -[3.0.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.2+Release%22 -[3.0.3-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.3+Release%22 -[3.0.4-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.4+Release%22 -[3.0.5-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.0.5+Release%22 -[3.1.0-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.1.0+Release%22 -[3.1.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.1.1+Release%22 -[3.1.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.1.2+Release%22 -[3.1.3-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.1.3+Release%22 -[3.2.0-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.0+Release%22 -[3.2.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.1+Release%22 -[3.2.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.2+Release%22 -[3.2.3-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.3+Release%22 -[3.2.4-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.4+Release%22 -[3.2.5-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.2.5+Release%22 -[3.3.0-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.3.0+Release%22 -[3.3.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.3.1+Release%22 -[3.3.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.3.2+Release%22 -[3.3.3-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.3.3+Release%22 -[3.4.0-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.0+Release%22 -[3.4.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.1+Release%22 -[3.4.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.2+Release%22 -[3.4.3-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.3+Release%22 -[3.4.4-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.4+Release%22 -[3.4.5-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.5+Release%22 -[3.4.6-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.6+Release%22 -[3.4.7-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.4.7+Release%22 -[3.5.0-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.5.0+Release%22 -[3.5.1-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.5.1+Release%22 -[3.5.2-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.5.2+Release%22 -[3.5.3-milestone]: https://github.com/tomchristie/django-rest-framework/issues?q=milestone%3A%223.5.3+Release%22 - - -[gh2013]: https://github.com/tomchristie/django-rest-framework/issues/2013 -[gh2098]: https://github.com/tomchristie/django-rest-framework/issues/2098 -[gh2109]: https://github.com/tomchristie/django-rest-framework/issues/2109 -[gh2135]: https://github.com/tomchristie/django-rest-framework/issues/2135 -[gh2163]: https://github.com/tomchristie/django-rest-framework/issues/2163 -[gh2168]: https://github.com/tomchristie/django-rest-framework/issues/2168 -[gh2169]: https://github.com/tomchristie/django-rest-framework/issues/2169 -[gh2172]: https://github.com/tomchristie/django-rest-framework/issues/2172 -[gh2175]: https://github.com/tomchristie/django-rest-framework/issues/2175 -[gh2184]: https://github.com/tomchristie/django-rest-framework/issues/2184 -[gh2187]: https://github.com/tomchristie/django-rest-framework/issues/2187 -[gh2193]: https://github.com/tomchristie/django-rest-framework/issues/2193 -[gh2194]: https://github.com/tomchristie/django-rest-framework/issues/2194 -[gh2195]: https://github.com/tomchristie/django-rest-framework/issues/2195 -[gh2196]: https://github.com/tomchristie/django-rest-framework/issues/2196 -[gh2197]: https://github.com/tomchristie/django-rest-framework/issues/2197 -[gh2200]: https://github.com/tomchristie/django-rest-framework/issues/2200 -[gh2202]: https://github.com/tomchristie/django-rest-framework/issues/2202 -[gh2205]: https://github.com/tomchristie/django-rest-framework/issues/2205 -[gh2213]: https://github.com/tomchristie/django-rest-framework/issues/2213 -[gh2213]: https://github.com/tomchristie/django-rest-framework/issues/2213 -[gh2215]: https://github.com/tomchristie/django-rest-framework/issues/2215 -[gh2225]: https://github.com/tomchristie/django-rest-framework/issues/2225 -[gh2231]: https://github.com/tomchristie/django-rest-framework/issues/2231 -[gh2232]: https://github.com/tomchristie/django-rest-framework/issues/2232 -[gh2239]: https://github.com/tomchristie/django-rest-framework/issues/2239 -[gh2242]: https://github.com/tomchristie/django-rest-framework/issues/2242 -[gh2243]: https://github.com/tomchristie/django-rest-framework/issues/2243 -[gh2244]: https://github.com/tomchristie/django-rest-framework/issues/2244 - -[gh2155]: https://github.com/tomchristie/django-rest-framework/issues/2155 -[gh2218]: https://github.com/tomchristie/django-rest-framework/issues/2218 -[gh2228]: https://github.com/tomchristie/django-rest-framework/issues/2228 -[gh2234]: https://github.com/tomchristie/django-rest-framework/issues/2234 -[gh2255]: https://github.com/tomchristie/django-rest-framework/issues/2255 -[gh2259]: https://github.com/tomchristie/django-rest-framework/issues/2259 -[gh2262]: https://github.com/tomchristie/django-rest-framework/issues/2262 -[gh2263]: https://github.com/tomchristie/django-rest-framework/issues/2263 -[gh2266]: https://github.com/tomchristie/django-rest-framework/issues/2266 -[gh2267]: https://github.com/tomchristie/django-rest-framework/issues/2267 -[gh2270]: https://github.com/tomchristie/django-rest-framework/issues/2270 -[gh2279]: https://github.com/tomchristie/django-rest-framework/issues/2279 -[gh2280]: https://github.com/tomchristie/django-rest-framework/issues/2280 -[gh2289]: https://github.com/tomchristie/django-rest-framework/issues/2289 -[gh2290]: https://github.com/tomchristie/django-rest-framework/issues/2290 -[gh2291]: https://github.com/tomchristie/django-rest-framework/issues/2291 -[gh2294]: https://github.com/tomchristie/django-rest-framework/issues/2294 - -[gh1101]: https://github.com/tomchristie/django-rest-framework/issues/1101 -[gh2010]: https://github.com/tomchristie/django-rest-framework/issues/2010 -[gh2278]: https://github.com/tomchristie/django-rest-framework/issues/2278 -[gh2283]: https://github.com/tomchristie/django-rest-framework/issues/2283 -[gh2287]: https://github.com/tomchristie/django-rest-framework/issues/2287 -[gh2311]: https://github.com/tomchristie/django-rest-framework/issues/2311 -[gh2315]: https://github.com/tomchristie/django-rest-framework/issues/2315 -[gh2317]: https://github.com/tomchristie/django-rest-framework/issues/2317 -[gh2319]: https://github.com/tomchristie/django-rest-framework/issues/2319 -[gh2327]: https://github.com/tomchristie/django-rest-framework/issues/2327 -[gh2330]: https://github.com/tomchristie/django-rest-framework/issues/2330 -[gh2331]: https://github.com/tomchristie/django-rest-framework/issues/2331 -[gh2340]: https://github.com/tomchristie/django-rest-framework/issues/2340 -[gh2342]: https://github.com/tomchristie/django-rest-framework/issues/2342 -[gh2351]: https://github.com/tomchristie/django-rest-framework/issues/2351 -[gh2355]: https://github.com/tomchristie/django-rest-framework/issues/2355 -[gh2369]: https://github.com/tomchristie/django-rest-framework/issues/2369 -[gh2386]: https://github.com/tomchristie/django-rest-framework/issues/2386 - -[gh2425]: https://github.com/tomchristie/django-rest-framework/issues/2425 -[gh2446]: https://github.com/tomchristie/django-rest-framework/issues/2446 -[gh2441]: https://github.com/tomchristie/django-rest-framework/issues/2441 -[gh2451]: https://github.com/tomchristie/django-rest-framework/issues/2451 -[gh2106]: https://github.com/tomchristie/django-rest-framework/issues/2106 -[gh2448]: https://github.com/tomchristie/django-rest-framework/issues/2448 -[gh2433]: https://github.com/tomchristie/django-rest-framework/issues/2433 -[gh2432]: https://github.com/tomchristie/django-rest-framework/issues/2432 -[gh2434]: https://github.com/tomchristie/django-rest-framework/issues/2434 -[gh2430]: https://github.com/tomchristie/django-rest-framework/issues/2430 -[gh2421]: https://github.com/tomchristie/django-rest-framework/issues/2421 -[gh2410]: https://github.com/tomchristie/django-rest-framework/issues/2410 -[gh2408]: https://github.com/tomchristie/django-rest-framework/issues/2408 -[gh2401]: https://github.com/tomchristie/django-rest-framework/issues/2401 -[gh2400]: https://github.com/tomchristie/django-rest-framework/issues/2400 -[gh2399]: https://github.com/tomchristie/django-rest-framework/issues/2399 -[gh2388]: https://github.com/tomchristie/django-rest-framework/issues/2388 -[gh2360]: https://github.com/tomchristie/django-rest-framework/issues/2360 - -[gh1850]: https://github.com/tomchristie/django-rest-framework/issues/1850 -[gh2108]: https://github.com/tomchristie/django-rest-framework/issues/2108 -[gh2475]: https://github.com/tomchristie/django-rest-framework/issues/2475 -[gh2479]: https://github.com/tomchristie/django-rest-framework/issues/2479 -[gh2486]: https://github.com/tomchristie/django-rest-framework/issues/2486 -[gh2492]: https://github.com/tomchristie/django-rest-framework/issues/2492 -[gh2518]: https://github.com/tomchristie/django-rest-framework/issues/2518 -[gh2519]: https://github.com/tomchristie/django-rest-framework/issues/2519 -[gh2524]: https://github.com/tomchristie/django-rest-framework/issues/2524 -[gh2530]: https://github.com/tomchristie/django-rest-framework/issues/2530 - -[gh2691]: https://github.com/tomchristie/django-rest-framework/issues/2691 -[gh2685]: https://github.com/tomchristie/django-rest-framework/issues/2685 -[gh2591]: https://github.com/tomchristie/django-rest-framework/issues/2591 -[gh2678]: https://github.com/tomchristie/django-rest-framework/issues/2678 -[gh2667]: https://github.com/tomchristie/django-rest-framework/issues/2667 -[gh2700]: https://github.com/tomchristie/django-rest-framework/issues/2700 -[gh2645]: https://github.com/tomchristie/django-rest-framework/issues/2645 -[gh2640]: https://github.com/tomchristie/django-rest-framework/issues/2640 -[gh2637]: https://github.com/tomchristie/django-rest-framework/issues/2637 -[gh2641]: https://github.com/tomchristie/django-rest-framework/issues/2641 -[gh2631]: https://github.com/tomchristie/django-rest-framework/issues/2631 -[gh2741]: https://github.com/tomchristie/django-rest-framework/issues/2641 -[gh2743]: https://github.com/tomchristie/django-rest-framework/issues/2643 - -[gh2656]: https://github.com/tomchristie/django-rest-framework/issues/2656 -[gh2687]: https://github.com/tomchristie/django-rest-framework/issues/2687 -[gh2869]: https://github.com/tomchristie/django-rest-framework/issues/2869 -[gh2764]: https://github.com/tomchristie/django-rest-framework/issues/2764 -[gh2763]: https://github.com/tomchristie/django-rest-framework/issues/2763 -[gh2757]: https://github.com/tomchristie/django-rest-framework/issues/2757 -[gh2630]: https://github.com/tomchristie/django-rest-framework/issues/2630 -[gh2724]: https://github.com/tomchristie/django-rest-framework/issues/2724 -[gh2711]: https://github.com/tomchristie/django-rest-framework/issues/2711 -[gh2745]: https://github.com/tomchristie/django-rest-framework/issues/2745 -[gh2754]: https://github.com/tomchristie/django-rest-framework/issues/2754 -[gh2762]: https://github.com/tomchristie/django-rest-framework/issues/2762 -[gh2798]: https://github.com/tomchristie/django-rest-framework/issues/2798 -[gh2807]: https://github.com/tomchristie/django-rest-framework/issues/2807 -[gh2818]: https://github.com/tomchristie/django-rest-framework/issues/2818 -[gh2835]: https://github.com/tomchristie/django-rest-framework/issues/2835 -[gh2836]: https://github.com/tomchristie/django-rest-framework/issues/2836 -[gh2853]: https://github.com/tomchristie/django-rest-framework/issues/2853 -[gh2862]: https://github.com/tomchristie/django-rest-framework/issues/2862 -[gh2863]: https://github.com/tomchristie/django-rest-framework/issues/2863 -[gh2868]: https://github.com/tomchristie/django-rest-framework/issues/2868 -[gh2905]: https://github.com/tomchristie/django-rest-framework/issues/2905 - -[gh2481]: https://github.com/tomchristie/django-rest-framework/issues/2481 -[gh2989]: https://github.com/tomchristie/django-rest-framework/issues/2989 -[gh2788]: https://github.com/tomchristie/django-rest-framework/issues/2788 -[gh3000]: https://github.com/tomchristie/django-rest-framework/issues/3000 -[gh2993]: https://github.com/tomchristie/django-rest-framework/issues/2993 -[gh2894]: https://github.com/tomchristie/django-rest-framework/issues/2894 -[gh2981]: https://github.com/tomchristie/django-rest-framework/issues/2981 -[gh2811]: https://github.com/tomchristie/django-rest-framework/issues/2811 -[gh2975]: https://github.com/tomchristie/django-rest-framework/issues/2975 -[gh2839]: https://github.com/tomchristie/django-rest-framework/issues/2839 -[gh2940]: https://github.com/tomchristie/django-rest-framework/issues/2940 -[gh2887]: https://github.com/tomchristie/django-rest-framework/issues/2887 -[gh2034]: https://github.com/tomchristie/django-rest-framework/issues/2034 -[gh2933]: https://github.com/tomchristie/django-rest-framework/issues/2933 -[gh2948]: https://github.com/tomchristie/django-rest-framework/issues/2948 -[gh2947]: https://github.com/tomchristie/django-rest-framework/issues/2947 -[gh2952]: https://github.com/tomchristie/django-rest-framework/issues/2952 -[gh2747]: https://github.com/tomchristie/django-rest-framework/issues/2747 -[gh2618]: https://github.com/tomchristie/django-rest-framework/issues/2618 -[gh3008]: https://github.com/tomchristie/django-rest-framework/issues/3008 -[gh2695]: https://github.com/tomchristie/django-rest-framework/issues/2695 - - -[gh1854]: https://github.com/tomchristie/django-rest-framework/issues/1854 -[gh2250]: https://github.com/tomchristie/django-rest-framework/issues/2250 -[gh2416]: https://github.com/tomchristie/django-rest-framework/issues/2416 -[gh2539]: https://github.com/tomchristie/django-rest-framework/issues/2539 -[gh2659]: https://github.com/tomchristie/django-rest-framework/issues/2659 -[gh2690]: https://github.com/tomchristie/django-rest-framework/issues/2690 -[gh2704]: https://github.com/tomchristie/django-rest-framework/issues/2704 -[gh2712]: https://github.com/tomchristie/django-rest-framework/issues/2712 -[gh2727]: https://github.com/tomchristie/django-rest-framework/issues/2727 -[gh2759]: https://github.com/tomchristie/django-rest-framework/issues/2759 -[gh2766]: https://github.com/tomchristie/django-rest-framework/issues/2766 -[gh2783]: https://github.com/tomchristie/django-rest-framework/issues/2783 -[gh2789]: https://github.com/tomchristie/django-rest-framework/issues/2789 -[gh2804]: https://github.com/tomchristie/django-rest-framework/issues/2804 -[gh2886]: https://github.com/tomchristie/django-rest-framework/issues/2886 -[gh2915]: https://github.com/tomchristie/django-rest-framework/issues/2915 -[gh2920]: https://github.com/tomchristie/django-rest-framework/issues/2920 -[gh2926]: https://github.com/tomchristie/django-rest-framework/issues/2926 -[gh2928]: https://github.com/tomchristie/django-rest-framework/issues/2928 -[gh2935]: https://github.com/tomchristie/django-rest-framework/issues/2935 -[gh3011]: https://github.com/tomchristie/django-rest-framework/issues/3011 -[gh3016]: https://github.com/tomchristie/django-rest-framework/issues/3016 -[gh3024]: https://github.com/tomchristie/django-rest-framework/issues/3024 -[gh3115]: https://github.com/tomchristie/django-rest-framework/issues/3115 -[gh3139]: https://github.com/tomchristie/django-rest-framework/issues/3139 -[gh3165]: https://github.com/tomchristie/django-rest-framework/issues/3165 -[gh3216]: https://github.com/tomchristie/django-rest-framework/issues/3216 -[gh3225]: https://github.com/tomchristie/django-rest-framework/issues/3225 - - -[gh3237]: https://github.com/tomchristie/django-rest-framework/issues/3237 -[gh3227]: https://github.com/tomchristie/django-rest-framework/issues/3227 -[gh3238]: https://github.com/tomchristie/django-rest-framework/issues/3238 -[gh3239]: https://github.com/tomchristie/django-rest-framework/issues/3239 - - -[gh3254]: https://github.com/tomchristie/django-rest-framework/issues/3254 -[gh3258]: https://github.com/tomchristie/django-rest-framework/issues/3258 -[gh2776]: https://github.com/tomchristie/django-rest-framework/issues/2776 -[gh3261]: https://github.com/tomchristie/django-rest-framework/issues/3261 -[gh3260]: https://github.com/tomchristie/django-rest-framework/issues/3260 -[gh3241]: https://github.com/tomchristie/django-rest-framework/issues/3241 - - -[gh3249]: https://github.com/tomchristie/django-rest-framework/issues/3249 -[gh3250]: https://github.com/tomchristie/django-rest-framework/issues/3250 -[gh3275]: https://github.com/tomchristie/django-rest-framework/issues/3275 -[gh3288]: https://github.com/tomchristie/django-rest-framework/issues/3288 -[gh3290]: https://github.com/tomchristie/django-rest-framework/issues/3290 -[gh3303]: https://github.com/tomchristie/django-rest-framework/issues/3303 -[gh3313]: https://github.com/tomchristie/django-rest-framework/issues/3313 -[gh3316]: https://github.com/tomchristie/django-rest-framework/issues/3316 -[gh3318]: https://github.com/tomchristie/django-rest-framework/issues/3318 -[gh3321]: https://github.com/tomchristie/django-rest-framework/issues/3321 - - -[gh2761]: https://github.com/tomchristie/django-rest-framework/issues/2761 -[gh3314]: https://github.com/tomchristie/django-rest-framework/issues/3314 -[gh3323]: https://github.com/tomchristie/django-rest-framework/issues/3323 -[gh3324]: https://github.com/tomchristie/django-rest-framework/issues/3324 -[gh3359]: https://github.com/tomchristie/django-rest-framework/issues/3359 -[gh3361]: https://github.com/tomchristie/django-rest-framework/issues/3361 -[gh3364]: https://github.com/tomchristie/django-rest-framework/issues/3364 -[gh3415]: https://github.com/tomchristie/django-rest-framework/issues/3415 - - -[gh3550]:https://github.com/tomchristie/django-rest-framework/issues/3550 - - -[gh3315]: https://github.com/tomchristie/django-rest-framework/issues/3315 -[gh3410]: https://github.com/tomchristie/django-rest-framework/issues/3410 -[gh3435]: https://github.com/tomchristie/django-rest-framework/issues/3435 -[gh3450]: https://github.com/tomchristie/django-rest-framework/issues/3450 -[gh3454]: https://github.com/tomchristie/django-rest-framework/issues/3454 -[gh3475]: https://github.com/tomchristie/django-rest-framework/issues/3475 -[gh3495]: https://github.com/tomchristie/django-rest-framework/issues/3495 -[gh3509]: https://github.com/tomchristie/django-rest-framework/issues/3509 -[gh3421]: https://github.com/tomchristie/django-rest-framework/issues/3421 -[gh3525]: https://github.com/tomchristie/django-rest-framework/issues/3525 -[gh3526]: https://github.com/tomchristie/django-rest-framework/issues/3526 -[gh3429]: https://github.com/tomchristie/django-rest-framework/issues/3429 -[gh3536]: https://github.com/tomchristie/django-rest-framework/issues/3536 - - -[gh3556]: https://github.com/tomchristie/django-rest-framework/issues/3556 -[gh3560]: https://github.com/tomchristie/django-rest-framework/issues/3560 -[gh3564]: https://github.com/tomchristie/django-rest-framework/issues/3564 -[gh3568]: https://github.com/tomchristie/django-rest-framework/issues/3568 -[gh3592]: https://github.com/tomchristie/django-rest-framework/issues/3592 -[gh3593]: https://github.com/tomchristie/django-rest-framework/issues/3593 - - -[gh3228]: https://github.com/tomchristie/django-rest-framework/issues/3228 -[gh3252]: https://github.com/tomchristie/django-rest-framework/issues/3252 -[gh3513]: https://github.com/tomchristie/django-rest-framework/issues/3513 -[gh3534]: https://github.com/tomchristie/django-rest-framework/issues/3534 -[gh3578]: https://github.com/tomchristie/django-rest-framework/issues/3578 -[gh3596]: https://github.com/tomchristie/django-rest-framework/issues/3596 -[gh3597]: https://github.com/tomchristie/django-rest-framework/issues/3597 -[gh3600]: https://github.com/tomchristie/django-rest-framework/issues/3600 -[gh3626]: https://github.com/tomchristie/django-rest-framework/issues/3626 -[gh3628]: https://github.com/tomchristie/django-rest-framework/issues/3628 -[gh3631]: https://github.com/tomchristie/django-rest-framework/issues/3631 -[gh3634]: https://github.com/tomchristie/django-rest-framework/issues/3634 -[gh3635]: https://github.com/tomchristie/django-rest-framework/issues/3635 -[gh3654]: https://github.com/tomchristie/django-rest-framework/issues/3654 -[gh3655]: https://github.com/tomchristie/django-rest-framework/issues/3655 -[gh3656]: https://github.com/tomchristie/django-rest-framework/issues/3656 -[gh3662]: https://github.com/tomchristie/django-rest-framework/issues/3662 -[gh3668]: https://github.com/tomchristie/django-rest-framework/issues/3668 -[gh3672]: https://github.com/tomchristie/django-rest-framework/issues/3672 -[gh3677]: https://github.com/tomchristie/django-rest-framework/issues/3677 -[gh3679]: https://github.com/tomchristie/django-rest-framework/issues/3679 -[gh3684]: https://github.com/tomchristie/django-rest-framework/issues/3684 -[gh3687]: https://github.com/tomchristie/django-rest-framework/issues/3687 -[gh3701]: https://github.com/tomchristie/django-rest-framework/issues/3701 -[gh3705]: https://github.com/tomchristie/django-rest-framework/issues/3705 -[gh3714]: https://github.com/tomchristie/django-rest-framework/issues/3714 -[gh3718]: https://github.com/tomchristie/django-rest-framework/issues/3718 -[gh3723]: https://github.com/tomchristie/django-rest-framework/issues/3723 - - -[gh3968]: https://github.com/tomchristie/django-rest-framework/issues/3968 -[gh3962]: https://github.com/tomchristie/django-rest-framework/issues/3962 -[gh3913]: https://github.com/tomchristie/django-rest-framework/issues/3913 -[gh3912]: https://github.com/tomchristie/django-rest-framework/issues/3912 -[gh3910]: https://github.com/tomchristie/django-rest-framework/issues/3910 -[gh3903]: https://github.com/tomchristie/django-rest-framework/issues/3903 -[gh3887]: https://github.com/tomchristie/django-rest-framework/issues/3887 -[gh3878]: https://github.com/tomchristie/django-rest-framework/issues/3878 -[gh3860]: https://github.com/tomchristie/django-rest-framework/issues/3860 -[gh3858]: https://github.com/tomchristie/django-rest-framework/issues/3858 -[gh3842]: https://github.com/tomchristie/django-rest-framework/issues/3842 -[gh3833]: https://github.com/tomchristie/django-rest-framework/issues/3833 -[gh3832]: https://github.com/tomchristie/django-rest-framework/issues/3832 -[gh3819]: https://github.com/tomchristie/django-rest-framework/issues/3819 -[gh3815]: https://github.com/tomchristie/django-rest-framework/issues/3815 -[gh3809]: https://github.com/tomchristie/django-rest-framework/issues/3809 -[gh3805]: https://github.com/tomchristie/django-rest-framework/issues/3805 -[gh3804]: https://github.com/tomchristie/django-rest-framework/issues/3804 -[gh3801]: https://github.com/tomchristie/django-rest-framework/issues/3801 -[gh3787]: https://github.com/tomchristie/django-rest-framework/issues/3787 -[gh3786]: https://github.com/tomchristie/django-rest-framework/issues/3786 -[gh3785]: https://github.com/tomchristie/django-rest-framework/issues/3785 -[gh3774]: https://github.com/tomchristie/django-rest-framework/issues/3774 -[gh3769]: https://github.com/tomchristie/django-rest-framework/issues/3769 -[gh3753]: https://github.com/tomchristie/django-rest-framework/issues/3753 -[gh3739]: https://github.com/tomchristie/django-rest-framework/issues/3739 -[gh3731]: https://github.com/tomchristie/django-rest-framework/issues/3731 -[gh3728]: https://github.com/tomchristie/django-rest-framework/issues/3726 -[gh3715]: https://github.com/tomchristie/django-rest-framework/issues/3715 -[gh3703]: https://github.com/tomchristie/django-rest-framework/issues/3703 -[gh3696]: https://github.com/tomchristie/django-rest-framework/issues/3696 -[gh3637]: https://github.com/tomchristie/django-rest-framework/issues/3637 -[gh3636]: https://github.com/tomchristie/django-rest-framework/issues/3636 -[gh3605]: https://github.com/tomchristie/django-rest-framework/issues/3605 -[gh3604]: https://github.com/tomchristie/django-rest-framework/issues/3604 - - -[gh2403]: https://github.com/tomchristie/django-rest-framework/issues/2403 -[gh2848]: https://github.com/tomchristie/django-rest-framework/issues/2848 -[gh2996]: https://github.com/tomchristie/django-rest-framework/issues/2996 -[gh3164]: https://github.com/tomchristie/django-rest-framework/issues/3164 -[gh3273]: https://github.com/tomchristie/django-rest-framework/issues/3273 -[gh3381]: https://github.com/tomchristie/django-rest-framework/issues/3381 -[gh3438]: https://github.com/tomchristie/django-rest-framework/issues/3438 -[gh3444]: https://github.com/tomchristie/django-rest-framework/issues/3444 -[gh3476]: https://github.com/tomchristie/django-rest-framework/issues/3476 -[gh3487]: https://github.com/tomchristie/django-rest-framework/issues/3487 -[gh3541]: https://github.com/tomchristie/django-rest-framework/issues/3541 -[gh3710]: https://github.com/tomchristie/django-rest-framework/issues/3710 -[gh3729]: https://github.com/tomchristie/django-rest-framework/issues/3729 -[gh3751]: https://github.com/tomchristie/django-rest-framework/issues/3751 -[gh3812]: https://github.com/tomchristie/django-rest-framework/issues/3812 -[gh3816]: https://github.com/tomchristie/django-rest-framework/issues/3816 -[gh3820]: https://github.com/tomchristie/django-rest-framework/issues/3820 -[gh3906]: https://github.com/tomchristie/django-rest-framework/issues/3906 -[gh3908]: https://github.com/tomchristie/django-rest-framework/issues/3908 -[gh3926]: https://github.com/tomchristie/django-rest-framework/issues/3926 -[gh3933]: https://github.com/tomchristie/django-rest-framework/issues/3933 -[gh3936]: https://github.com/tomchristie/django-rest-framework/issues/3936 -[gh3938]: https://github.com/tomchristie/django-rest-framework/issues/3938 -[gh3943]: https://github.com/tomchristie/django-rest-framework/issues/3943 -[gh3953]: https://github.com/tomchristie/django-rest-framework/issues/3953 -[gh3964]: https://github.com/tomchristie/django-rest-framework/issues/3964 -[gh3968]: https://github.com/tomchristie/django-rest-framework/issues/3968 -[gh3970]: https://github.com/tomchristie/django-rest-framework/issues/3970 -[gh3971]: https://github.com/tomchristie/django-rest-framework/issues/3971 -[gh3976]: https://github.com/tomchristie/django-rest-framework/issues/3976 -[gh3983]: https://github.com/tomchristie/django-rest-framework/issues/3983 -[gh3990]: https://github.com/tomchristie/django-rest-framework/issues/3990 -[gh4002]: https://github.com/tomchristie/django-rest-framework/issues/4002 -[gh4003]: https://github.com/tomchristie/django-rest-framework/issues/4003 -[gh4005]: https://github.com/tomchristie/django-rest-framework/issues/4005 -[gh4006]: https://github.com/tomchristie/django-rest-framework/issues/4006 -[gh4008]: https://github.com/tomchristie/django-rest-framework/issues/4008 -[gh4021]: https://github.com/tomchristie/django-rest-framework/issues/4021 -[gh4025]: https://github.com/tomchristie/django-rest-framework/issues/4025 -[gh4040]: https://github.com/tomchristie/django-rest-framework/issues/4040 -[gh4041]: https://github.com/tomchristie/django-rest-framework/issues/4041 -[gh4049]: https://github.com/tomchristie/django-rest-framework/issues/4049 -[gh4075]: https://github.com/tomchristie/django-rest-framework/issues/4075 -[gh4079]: https://github.com/tomchristie/django-rest-framework/issues/4079 -[gh4090]: https://github.com/tomchristie/django-rest-framework/issues/4090 -[gh4097]: https://github.com/tomchristie/django-rest-framework/issues/4097 -[gh4098]: https://github.com/tomchristie/django-rest-framework/issues/4098 -[gh4103]: https://github.com/tomchristie/django-rest-framework/issues/4103 -[gh4105]: https://github.com/tomchristie/django-rest-framework/issues/4105 -[gh4106]: https://github.com/tomchristie/django-rest-framework/issues/4106 -[gh4107]: https://github.com/tomchristie/django-rest-framework/issues/4107 -[gh4118]: https://github.com/tomchristie/django-rest-framework/issues/4118 -[gh4146]: https://github.com/tomchristie/django-rest-framework/issues/4146 -[gh4149]: https://github.com/tomchristie/django-rest-framework/issues/4149 -[gh4153]: https://github.com/tomchristie/django-rest-framework/issues/4153 -[gh4156]: https://github.com/tomchristie/django-rest-framework/issues/4156 -[gh4157]: https://github.com/tomchristie/django-rest-framework/issues/4157 -[gh4158]: https://github.com/tomchristie/django-rest-framework/issues/4158 -[gh4166]: https://github.com/tomchristie/django-rest-framework/issues/4166 -[gh4176]: https://github.com/tomchristie/django-rest-framework/issues/4176 -[gh4179]: https://github.com/tomchristie/django-rest-framework/issues/4179 -[gh4180]: https://github.com/tomchristie/django-rest-framework/issues/4180 -[gh4181]: https://github.com/tomchristie/django-rest-framework/issues/4181 -[gh4185]: https://github.com/tomchristie/django-rest-framework/issues/4185 -[gh4187]: https://github.com/tomchristie/django-rest-framework/issues/4187 -[gh4191]: https://github.com/tomchristie/django-rest-framework/issues/4191 -[gh4192]: https://github.com/tomchristie/django-rest-framework/issues/4192 -[gh4194]: https://github.com/tomchristie/django-rest-framework/issues/4194 -[gh4195]: https://github.com/tomchristie/django-rest-framework/issues/4195 -[gh4196]: https://github.com/tomchristie/django-rest-framework/issues/4196 -[gh4212]: https://github.com/tomchristie/django-rest-framework/issues/4212 -[gh4215]: https://github.com/tomchristie/django-rest-framework/issues/4215 -[gh4217]: https://github.com/tomchristie/django-rest-framework/issues/4217 -[gh4219]: https://github.com/tomchristie/django-rest-framework/issues/4219 -[gh4229]: https://github.com/tomchristie/django-rest-framework/issues/4229 -[gh4233]: https://github.com/tomchristie/django-rest-framework/issues/4233 -[gh4244]: https://github.com/tomchristie/django-rest-framework/issues/4244 -[gh4246]: https://github.com/tomchristie/django-rest-framework/issues/4246 -[gh4253]: https://github.com/tomchristie/django-rest-framework/issues/4253 -[gh4254]: https://github.com/tomchristie/django-rest-framework/issues/4254 -[gh4255]: https://github.com/tomchristie/django-rest-framework/issues/4255 -[gh4256]: https://github.com/tomchristie/django-rest-framework/issues/4256 -[gh4259]: https://github.com/tomchristie/django-rest-framework/issues/4259 - - -[gh4323]: https://github.com/tomchristie/django-rest-framework/issues/4323 -[gh4268]: https://github.com/tomchristie/django-rest-framework/issues/4268 -[gh4321]: https://github.com/tomchristie/django-rest-framework/issues/4321 -[gh4308]: https://github.com/tomchristie/django-rest-framework/issues/4308 -[gh4305]: https://github.com/tomchristie/django-rest-framework/issues/4305 -[gh4316]: https://github.com/tomchristie/django-rest-framework/issues/4316 -[gh4294]: https://github.com/tomchristie/django-rest-framework/issues/4294 -[gh4293]: https://github.com/tomchristie/django-rest-framework/issues/4293 -[gh4315]: https://github.com/tomchristie/django-rest-framework/issues/4315 -[gh4314]: https://github.com/tomchristie/django-rest-framework/issues/4314 -[gh4289]: https://github.com/tomchristie/django-rest-framework/issues/4289 -[gh4265]: https://github.com/tomchristie/django-rest-framework/issues/4265 -[gh4285]: https://github.com/tomchristie/django-rest-framework/issues/4285 -[gh4287]: https://github.com/tomchristie/django-rest-framework/issues/4287 -[gh4313]: https://github.com/tomchristie/django-rest-framework/issues/4313 -[gh4281]: https://github.com/tomchristie/django-rest-framework/issues/4281 -[gh4299]: https://github.com/tomchristie/django-rest-framework/issues/4299 -[gh4307]: https://github.com/tomchristie/django-rest-framework/issues/4307 -[gh4302]: https://github.com/tomchristie/django-rest-framework/issues/4302 -[gh4303]: https://github.com/tomchristie/django-rest-framework/issues/4303 -[gh4298]: https://github.com/tomchristie/django-rest-framework/issues/4298 -[gh4291]: https://github.com/tomchristie/django-rest-framework/issues/4291 -[gh4270]: https://github.com/tomchristie/django-rest-framework/issues/4270 -[gh4272]: https://github.com/tomchristie/django-rest-framework/issues/4272 -[gh4273]: https://github.com/tomchristie/django-rest-framework/issues/4273 -[gh4288]: https://github.com/tomchristie/django-rest-framework/issues/4288 - - -[gh3565]: https://github.com/tomchristie/django-rest-framework/issues/3565 -[gh3610]: https://github.com/tomchristie/django-rest-framework/issues/3610 -[gh4198]: https://github.com/tomchristie/django-rest-framework/issues/4198 -[gh4199]: https://github.com/tomchristie/django-rest-framework/issues/4199 -[gh4236]: https://github.com/tomchristie/django-rest-framework/issues/4236 -[gh4292]: https://github.com/tomchristie/django-rest-framework/issues/4292 -[gh4296]: https://github.com/tomchristie/django-rest-framework/issues/4296 -[gh4318]: https://github.com/tomchristie/django-rest-framework/issues/4318 -[gh4330]: https://github.com/tomchristie/django-rest-framework/issues/4330 -[gh4331]: https://github.com/tomchristie/django-rest-framework/issues/4331 -[gh4332]: https://github.com/tomchristie/django-rest-framework/issues/4332 -[gh4335]: https://github.com/tomchristie/django-rest-framework/issues/4335 -[gh4336]: https://github.com/tomchristie/django-rest-framework/issues/4336 -[gh4338]: https://github.com/tomchristie/django-rest-framework/issues/4338 -[gh4339]: https://github.com/tomchristie/django-rest-framework/issues/4339 -[gh4340]: https://github.com/tomchristie/django-rest-framework/issues/4340 -[gh4344]: https://github.com/tomchristie/django-rest-framework/issues/4344 -[gh4345]: https://github.com/tomchristie/django-rest-framework/issues/4345 -[gh4346]: https://github.com/tomchristie/django-rest-framework/issues/4346 -[gh4347]: https://github.com/tomchristie/django-rest-framework/issues/4347 -[gh4348]: https://github.com/tomchristie/django-rest-framework/issues/4348 -[gh4349]: https://github.com/tomchristie/django-rest-framework/issues/4349 -[gh4354]: https://github.com/tomchristie/django-rest-framework/issues/4354 -[gh4357]: https://github.com/tomchristie/django-rest-framework/issues/4357 -[gh4358]: https://github.com/tomchristie/django-rest-framework/issues/4358 -[gh4359]: https://github.com/tomchristie/django-rest-framework/issues/4359 - - -[gh4361]: https://github.com/tomchristie/django-rest-framework/issues/4361 - - - -[gh2829]: https://github.com/tomchristie/django-rest-framework/issues/2829 -[gh3329]: https://github.com/tomchristie/django-rest-framework/issues/3329 -[gh3330]: https://github.com/tomchristie/django-rest-framework/issues/3330 -[gh3365]: https://github.com/tomchristie/django-rest-framework/issues/3365 -[gh3394]: https://github.com/tomchristie/django-rest-framework/issues/3394 -[gh3868]: https://github.com/tomchristie/django-rest-framework/issues/3868 -[gh3868]: https://github.com/tomchristie/django-rest-framework/issues/3868 -[gh3877]: https://github.com/tomchristie/django-rest-framework/issues/3877 -[gh4042]: https://github.com/tomchristie/django-rest-framework/issues/4042 -[gh4111]: https://github.com/tomchristie/django-rest-framework/issues/4111 -[gh4119]: https://github.com/tomchristie/django-rest-framework/issues/4119 -[gh4120]: https://github.com/tomchristie/django-rest-framework/issues/4120 -[gh4121]: https://github.com/tomchristie/django-rest-framework/issues/4121 -[gh4122]: https://github.com/tomchristie/django-rest-framework/issues/4122 -[gh4137]: https://github.com/tomchristie/django-rest-framework/issues/4137 -[gh4172]: https://github.com/tomchristie/django-rest-framework/issues/4172 -[gh4201]: https://github.com/tomchristie/django-rest-framework/issues/4201 -[gh4260]: https://github.com/tomchristie/django-rest-framework/issues/4260 -[gh4278]: https://github.com/tomchristie/django-rest-framework/issues/4278 -[gh4279]: https://github.com/tomchristie/django-rest-framework/issues/4279 -[gh4329]: https://github.com/tomchristie/django-rest-framework/issues/4329 -[gh4370]: https://github.com/tomchristie/django-rest-framework/issues/4370 -[gh4371]: https://github.com/tomchristie/django-rest-framework/issues/4371 -[gh4372]: https://github.com/tomchristie/django-rest-framework/issues/4372 -[gh4373]: https://github.com/tomchristie/django-rest-framework/issues/4373 -[gh4374]: https://github.com/tomchristie/django-rest-framework/issues/4374 -[gh4375]: https://github.com/tomchristie/django-rest-framework/issues/4375 -[gh4376]: https://github.com/tomchristie/django-rest-framework/issues/4376 -[gh4377]: https://github.com/tomchristie/django-rest-framework/issues/4377 -[gh4378]: https://github.com/tomchristie/django-rest-framework/issues/4378 -[gh4379]: https://github.com/tomchristie/django-rest-framework/issues/4379 -[gh4380]: https://github.com/tomchristie/django-rest-framework/issues/4380 -[gh4382]: https://github.com/tomchristie/django-rest-framework/issues/4382 -[gh4383]: https://github.com/tomchristie/django-rest-framework/issues/4383 -[gh4386]: https://github.com/tomchristie/django-rest-framework/issues/4386 -[gh4387]: https://github.com/tomchristie/django-rest-framework/issues/4387 -[gh4388]: https://github.com/tomchristie/django-rest-framework/issues/4388 -[gh4390]: https://github.com/tomchristie/django-rest-framework/issues/4390 -[gh4391]: https://github.com/tomchristie/django-rest-framework/issues/4391 -[gh4392]: https://github.com/tomchristie/django-rest-framework/issues/4392 -[gh4393]: https://github.com/tomchristie/django-rest-framework/issues/4393 -[gh4394]: https://github.com/tomchristie/django-rest-framework/issues/4394 - - -[gh4416]: https://github.com/tomchristie/django-rest-framework/issues/4416 -[gh4409]: https://github.com/tomchristie/django-rest-framework/issues/4409 -[gh4415]: https://github.com/tomchristie/django-rest-framework/issues/4415 -[gh4410]: https://github.com/tomchristie/django-rest-framework/issues/4410 -[gh4408]: https://github.com/tomchristie/django-rest-framework/issues/4408 -[gh4398]: https://github.com/tomchristie/django-rest-framework/issues/4398 -[gh4407]: https://github.com/tomchristie/django-rest-framework/issues/4407 -[gh4403]: https://github.com/tomchristie/django-rest-framework/issues/4403 -[gh4404]: https://github.com/tomchristie/django-rest-framework/issues/4404 -[gh4412]: https://github.com/tomchristie/django-rest-framework/issues/4412 - - - -[gh4435]: https://github.com/tomchristie/django-rest-framework/issues/4435 -[gh4425]: https://github.com/tomchristie/django-rest-framework/issues/4425 -[gh4429]: https://github.com/tomchristie/django-rest-framework/issues/4429 -[gh3508]: https://github.com/tomchristie/django-rest-framework/issues/3508 -[gh4419]: https://github.com/tomchristie/django-rest-framework/issues/4419 -[gh4423]: https://github.com/tomchristie/django-rest-framework/issues/4423 - - - -[gh3951]: https://github.com/tomchristie/django-rest-framework/issues/3951 -[gh4500]: https://github.com/tomchristie/django-rest-framework/issues/4500 -[gh4489]: https://github.com/tomchristie/django-rest-framework/issues/4489 -[gh4490]: https://github.com/tomchristie/django-rest-framework/issues/4490 -[gh2617]: https://github.com/tomchristie/django-rest-framework/issues/2617 -[gh4472]: https://github.com/tomchristie/django-rest-framework/issues/4472 -[gh4473]: https://github.com/tomchristie/django-rest-framework/issues/4473 -[gh4495]: https://github.com/tomchristie/django-rest-framework/issues/4495 -[gh4493]: https://github.com/tomchristie/django-rest-framework/issues/4493 -[gh4465]: https://github.com/tomchristie/django-rest-framework/issues/4465 -[gh4462]: https://github.com/tomchristie/django-rest-framework/issues/4462 -[gh4458]: https://github.com/tomchristie/django-rest-framework/issues/4458 - - - -[gh4612]: https://github.com/tomchristie/django-rest-framework/issues/4612 -[gh4608]: https://github.com/tomchristie/django-rest-framework/issues/4608 -[gh4601]: https://github.com/tomchristie/django-rest-framework/issues/4601 -[gh4611]: https://github.com/tomchristie/django-rest-framework/issues/4611 -[gh4605]: https://github.com/tomchristie/django-rest-framework/issues/4605 -[gh4609]: https://github.com/tomchristie/django-rest-framework/issues/4609 -[gh4606]: https://github.com/tomchristie/django-rest-framework/issues/4606 -[gh4600]: https://github.com/tomchristie/django-rest-framework/issues/4600 - - - -[gh4631]: https://github.com/tomchristie/django-rest-framework/issues/4631 -[gh4638]: https://github.com/tomchristie/django-rest-framework/issues/4638 -[gh4532]: https://github.com/tomchristie/django-rest-framework/issues/4532 -[gh4636]: https://github.com/tomchristie/django-rest-framework/issues/4636 -[gh4622]: https://github.com/tomchristie/django-rest-framework/issues/4622 -[gh4602]: https://github.com/tomchristie/django-rest-framework/issues/4602 -[gh4640]: https://github.com/tomchristie/django-rest-framework/issues/4640 -[gh4624]: https://github.com/tomchristie/django-rest-framework/issues/4624 -[gh4569]: https://github.com/tomchristie/django-rest-framework/issues/4569 -[gh4627]: https://github.com/tomchristie/django-rest-framework/issues/4627 -[gh4620]: https://github.com/tomchristie/django-rest-framework/issues/4620 -[gh4628]: https://github.com/tomchristie/django-rest-framework/issues/4628 -[gh4639]: https://github.com/tomchristie/django-rest-framework/issues/4639 - - - -[gh4660]: https://github.com/tomchristie/django-rest-framework/issues/4660 -[gh4643]: https://github.com/tomchristie/django-rest-framework/issues/4643 -[gh4644]: https://github.com/tomchristie/django-rest-framework/issues/4644 -[gh4645]: https://github.com/tomchristie/django-rest-framework/issues/4645 -[gh4646]: https://github.com/tomchristie/django-rest-framework/issues/4646 -[gh4650]: https://github.com/tomchristie/django-rest-framework/issues/4650 diff --git a/docs/topics/rest-framework-2-announcement.md b/docs/topics/rest-framework-2-announcement.md deleted file mode 100644 index ed41bb4864..0000000000 --- a/docs/topics/rest-framework-2-announcement.md +++ /dev/null @@ -1,98 +0,0 @@ -# Django REST framework 2.0 - -> Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. -> -> — [Roy Fielding][cite] - ---- - -**Announcement:** REST framework 2 released - Tue 30th Oct 2012 - ---- - -REST framework 2 is an almost complete reworking of the original framework, which comprehensively addresses some of the original design issues. - -Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0. - -This article is intended to give you a flavor of what REST framework 2 is, and why you might want to give it a try. - -## User feedback - -Before we get cracking, let's start with the hard sell, with a few bits of feedback from some early adopters… - -"Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz." - [Kit La Touche][quote1] - -"Since it's pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2] has definitely got the right approach here; even simple things like being able to override a function called post to do custom work during rather than having to intimately know what happens during a post make a huge difference to your productivity." - [Ian Strachan][quote2] - -"I switched to the 2.0 branch and I don't regret it - fully refactored my code in another ½ day and it's *much* more to my tastes" - [Bruno Desthuilliers][quote3] - -Sounds good, right? Let's get into some details... - -## Serialization - -REST framework 2 includes a totally re-worked serialization engine, that was initially intended as a replacement for Django's existing inflexible fixture serialization, and which meets the following design goals: - -* A declarative serialization API, that mirrors Django's `Forms`/`ModelForms` API. -* Structural concerns are decoupled from encoding concerns. -* Able to support rendering and parsing to many formats, including both machine-readable representations and HTML forms. -* Validation that can be mapped to obvious and comprehensive error responses. -* Serializers that support both nested, flat, and partially-nested representations. -* Relationships that can be expressed as primary keys, hyperlinks, slug fields, and other custom representations. - -Mapping between the internal state of the system and external representations of that state is the core concern of building Web APIs. Designing serializers that allow the developer to do so in a flexible and obvious way is a deceptively difficult design task, and with the new serialization API we think we've pretty much nailed it. - -## Generic views - -When REST framework was initially released at the start of 2011, the current Django release was version 1.2. REST framework included a backport of Django 1.3's upcoming `View` class, but it didn't take full advantage of the generic view implementations. - -With the new release the generic views in REST framework now tie in with Django's generic views. The end result is that framework is clean, lightweight and easy to use. - -## Requests, Responses & Views - -REST framework 2 includes `Request` and `Response` classes, than are used in place of Django's existing `HttpRequest` and `HttpResponse` classes. Doing so allows logic such as parsing the incoming request or rendering the outgoing response to be supported transparently by the framework. - -The `Request`/`Response` approach leads to a much cleaner API, less logic in the view itself, and a simple, obvious request-response cycle. - -REST framework 2 also allows you to work with both function-based and class-based views. For simple API views all you need is a single `@api_view` decorator, and you're good to go. - - -## API Design - -Pretty much every aspect of REST framework has been reworked, with the aim of ironing out some of the design flaws of the previous versions. Each of the components of REST framework are cleanly decoupled, and can be used independently of each-other, and there are no monolithic resource classes, overcomplicated mixin combinations, or opinionated serialization or URL routing decisions. - -## The Browsable API - -Django REST framework's most unique feature is the way it is able to serve up both machine-readable representations, and a fully browsable HTML representation to the same endpoints. - -Browsable Web APIs are easier to work with, visualize and debug, and generally makes it easier and more frictionless to inspect and work with. - -With REST framework 2, the browsable API gets a snazzy new bootstrap-based theme that looks great and is even nicer to work with. - -There are also some functionality improvements - actions such as as `POST` and `DELETE` will only display if the user has the appropriate permissions. - -![Browsable API][image] - -**Image above**: An example of the browsable API in REST framework 2 - -## Documentation - -As you can see the documentation for REST framework has been radically improved. It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling. - -We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great. - -## Summary - -In short, we've engineered the hell outta this thing, and we're incredibly proud of the result. - -If you're interested please take a browse around the documentation. [The tutorial][tut] is a great place to get started. - -There's also a [live sandbox version of the tutorial API][sandbox] available for testing. - -[cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724 -[quote1]: https://twitter.com/kobutsu/status/261689665952833536 -[quote2]: https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J -[quote3]: https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ -[image]: ../img/quickstart.png -[readthedocs]: https://readthedocs.org/ -[tut]: ../tutorial/1-serialization.md -[sandbox]: http://restframework.herokuapp.com/ diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 5517b150cd..d48319a269 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -34,15 +34,14 @@ 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]: http://vimeo.com/channels/restfest/page:2 -[dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm -[hypertext-driven]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven +[cite]: https://vimeo.com/channels/restfest/page:2 +[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/ -[building-hypermedia-apis]: http://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578 +[building-hypermedia-apis]: https://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578 [designing-hypermedia-apis]: http://designinghypermediaapis.com/ -[restisover]: http://blog.steveklabnik.com/posts/2012-02-23-rest-is-over [readinglist]: http://blog.steveklabnik.com/posts/2012-02-27-hypermedia-api-reading-list -[maturitymodel]: http://martinfowler.com/articles/richardsonMaturityModel.html +[maturitymodel]: https://martinfowler.com/articles/richardsonMaturityModel.html [hal]: http://stateless.co/hal_specification.html [collection]: http://www.amundsen.com/media-types/collection/ diff --git a/docs/topics/writable-nested-serializers.md b/docs/topics/writable-nested-serializers.md index cab700e5b8..3bac84ffa9 100644 --- a/docs/topics/writable-nested-serializers.md +++ b/docs/topics/writable-nested-serializers.md @@ -12,22 +12,22 @@ Nested data structures are easy enough to work with if they're read-only - simpl *Example of a **read-only** nested serializer. Nothing complex to worry about here.* - class ToDoItemSerializer(serializers.ModelSerializer): - class Meta: - model = ToDoItem - fields = ('text', 'is_completed') + class ToDoItemSerializer(serializers.ModelSerializer): + class Meta: + model = ToDoItem + fields = ['text', 'is_completed'] - class ToDoListSerializer(serializers.ModelSerializer): - items = ToDoItemSerializer(many=True, read_only=True) + class ToDoListSerializer(serializers.ModelSerializer): + items = ToDoItemSerializer(many=True, read_only=True) - class Meta: - model = ToDoList - fields = ('title', 'items') + class Meta: + model = ToDoList + fields = ['title', 'items'] Some example output from our serializer. { - 'title': 'Leaving party preperations', + 'title': 'Leaving party preparations', 'items': [ {'text': 'Compile playlist', 'is_completed': True}, {'text': 'Send invites', 'is_completed': False}, diff --git a/docs/tutorial/1-serialization.md b/docs/tutorial/1-serialization.md index 04fb6914ac..85d8676b1d 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 @@ -33,7 +33,7 @@ Okay, we're ready to get coding. To get started, let's create a new project to work with. cd ~ - django-admin.py startproject tutorial + django-admin startproject tutorial cd tutorial Once that's done we can create an app that we'll use to create a simple Web API. @@ -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', - ) + ] 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,7 +72,7 @@ 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. @@ -137,26 +137,26 @@ Okay, once we've got a few imports out of the way, let's create a couple of code snippet = Snippet(code='foo = "bar"\n') snippet.save() - snippet = Snippet(code='print "hello, world"\n') + snippet = Snippet(code='print("hello, world")\n') snippet.save() We've now got a few snippet instances to play with. Let's take a look at serializing one of those instances. serializer = SnippetSerializer(snippet) serializer.data - # {'id': 2, 'title': u'', 'code': u'print "hello, world"\n', 'linenos': False, 'language': u'python', 'style': u'friendly'} + # {'id': 2, 'title': '', 'code': 'print("hello, world")\n', 'linenos': False, 'language': 'python', 'style': 'friendly'} At this point we've translated the model instance into Python native datatypes. To finalize the serialization process we render the data into `json`. content = JSONRenderer().render(serializer.data) content - # '{"id": 2, "title": "", "code": "print \\"hello, world\\"\\n", "linenos": false, "language": "python", "style": "friendly"}' + # b'{"id": 2, "title": "", "code": "print(\\"hello, world\\")\\n", "linenos": false, "language": "python", "style": "friendly"}' Deserialization is similar. First we parse a stream into Python native datatypes... - from django.utils.six import BytesIO + import io - stream = BytesIO(content) + stream = io.BytesIO(content) data = JSONParser().parse(stream) ...then we restore those native datatypes into a fully populated object instance. @@ -165,7 +165,7 @@ Deserialization is similar. First we parse a stream into Python native datatype serializer.is_valid() # True serializer.validated_data - # OrderedDict([('title', ''), ('code', 'print "hello, world"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]) + # OrderedDict([('title', ''), ('code', 'print("hello, world")\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]) serializer.save() # @@ -175,7 +175,7 @@ We can also serialize querysets instead of model instances. To do so we simply serializer = SnippetSerializer(Snippet.objects.all(), many=True) serializer.data - # [OrderedDict([('id', 1), ('title', u''), ('code', u'foo = "bar"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 2), ('title', u''), ('code', u'print "hello, world"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 3), ('title', u''), ('code', u'print "hello, world"'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])] + # [OrderedDict([('id', 1), ('title', ''), ('code', 'foo = "bar"\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 2), ('title', ''), ('code', 'print("hello, world")\n'), ('linenos', False), ('language', 'python'), ('style', 'friendly')]), OrderedDict([('id', 3), ('title', ''), ('code', 'print("hello, world")'), ('linenos', False), ('language', 'python'), ('style', 'friendly')])] ## Using ModelSerializers @@ -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: @@ -214,26 +214,14 @@ It's important to remember that `ModelSerializer` classes don't do anything part Let's see how we can write some API views using our new Serializer class. For the moment we won't use any of REST framework's other features, we'll just write the views as regular Django views. -We'll start off by creating a subclass of HttpResponse that we can use to render any data we return into `json`. - Edit the `snippets/views.py` file, and add the following. - from django.http import HttpResponse + 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 - class JSONResponse(HttpResponse): - """ - An HttpResponse that renders its content into JSON. - """ - def __init__(self, data, **kwargs): - content = JSONRenderer().render(data) - kwargs['content_type'] = 'application/json' - super(JSONResponse, self).__init__(content, **kwargs) - The root of our API is going to be a view that supports listing all the existing snippets, or creating a new snippet. @csrf_exempt @@ -244,15 +232,15 @@ The root of our API is going to be a view that supports listing all the existing if request.method == 'GET': snippets = Snippet.objects.all() serializer = SnippetSerializer(snippets, many=True) - return JSONResponse(serializer.data) + return JsonResponse(serializer.data, safe=False) elif request.method == 'POST': data = JSONParser().parse(request) serializer = SnippetSerializer(data=data) if serializer.is_valid(): serializer.save() - return JSONResponse(serializer.data, status=201) - return JSONResponse(serializer.errors, status=400) + return JsonResponse(serializer.data, status=201) + return JsonResponse(serializer.errors, status=400) Note that because we want to be able to POST to this view from clients that won't have a CSRF token we need to mark the view as `csrf_exempt`. This isn't something that you'd normally want to do, and REST framework views actually use more sensible behavior than this, but it'll do for our purposes right now. @@ -270,15 +258,15 @@ We'll also need a view which corresponds to an individual snippet, and can be us if request.method == 'GET': serializer = SnippetSerializer(snippet) - return JSONResponse(serializer.data) + return JsonResponse(serializer.data) elif request.method == 'PUT': data = JSONParser().parse(request) serializer = SnippetSerializer(snippet, data=data) if serializer.is_valid(): serializer.save() - return JSONResponse(serializer.data) - return JSONResponse(serializer.errors, status=400) + return JsonResponse(serializer.data) + return JsonResponse(serializer.errors, status=400) elif request.method == 'DELETE': snippet.delete() @@ -286,20 +274,20 @@ We'll also need a view which corresponds to an individual snippet, and can be us Finally we need to wire these views up. Create the `snippets/urls.py` file: - from django.conf.urls import url + from django.urls import path from snippets import views urlpatterns = [ - url(r'^snippets/$', views.snippet_list), - url(r'^snippets/(?P[0-9]+)/$', views.snippet_detail), + path('snippets/', views.snippet_list), + path('snippets//', views.snippet_detail), ] We also need to wire up the root urlconf, in the `tutorial/urls.py` file, to include our snippet app's URLs. - from django.conf.urls import url, include + from django.urls import path, include urlpatterns = [ - url(r'^', include('snippets.urls')), + path('', include('snippets.urls')), ] It's worth noting that there are a couple of edge cases we're not dealing with properly at the moment. If we send malformed `json`, or if a request is made with a method that the view doesn't handle, then we'll end up with a 500 "server error" response. Still, this'll do for now. @@ -310,18 +298,18 @@ Now we can start up a sample server that serves our snippets. Quit out of the shell... - quit() + quit() ...and start up Django's development server. - python manage.py runserver + python manage.py runserver - Validating models... + Validating models... - 0 errors found - Django version 1.8.3, using settings 'tutorial.settings' - Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C. + 0 errors found + Django version 1.11, using settings 'tutorial.settings' + Development server is running at http://127.0.0.1:8000/ + Quit the server with CONTROL-C. In another terminal window, we can test the server. @@ -349,7 +337,7 @@ Finally, we can get a list of all of the snippets: { "id": 2, "title": "", - "code": "print \"hello, world\"\n", + "code": "print(\"hello, world\")\n", "linenos": false, "language": "python", "style": "friendly" @@ -365,7 +353,7 @@ Or we can get a particular snippet by referencing its id: { "id": 2, "title": "", - "code": "print \"hello, world\"\n", + "code": "print(\"hello, world\")\n", "linenos": false, "language": "python", "style": "friendly" @@ -382,9 +370,9 @@ Our API views don't do anything particularly special at the moment, beyond servi 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/tomchristie/rest-framework-tutorial -[sandbox]: http://restframework.herokuapp.com/ -[virtualenv]: http://www.virtualenv.org/en/latest/index.html +[repo]: https://github.com/encode/rest-framework-tutorial +[sandbox]: https://restframework.herokuapp.com/ +[venv]: https://docs.python.org/3/library/venv.html [tut-2]: 2-requests-and-responses.md [httpie]: https://github.com/jakubroztocil/httpie#installation -[curl]: http://curl.haxx.se +[curl]: https://curl.haxx.se/ diff --git a/docs/tutorial/2-requests-and-responses.md b/docs/tutorial/2-requests-and-responses.md index 5c020a1f70..b6433695ad 100644 --- a/docs/tutorial/2-requests-and-responses.md +++ b/docs/tutorial/2-requests-and-responses.md @@ -33,9 +33,7 @@ The wrappers also provide behaviour such as returning `405 Method Not Allowed` r ## 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` anymore, 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 @@ -47,7 +45,7 @@ We don't need our `JSONResponse` class in `views.py` anymore, so go ahead and de @api_view(['GET', 'POST']) def snippet_list(request): """ - List all snippets, or create a new snippet. + List all code snippets, or create a new snippet. """ if request.method == 'GET': snippets = Snippet.objects.all() @@ -68,7 +66,7 @@ Here is the view for an individual snippet, in the `views.py` module. @api_view(['GET', 'PUT', 'DELETE']) def snippet_detail(request, pk): """ - Retrieve, update or delete a snippet instance. + Retrieve, update or delete a code snippet. """ try: snippet = Snippet.objects.get(pk=pk) @@ -106,15 +104,15 @@ and def snippet_detail(request, pk, format=None): -Now update the `urls.py` file slightly, to append a set of `format_suffix_patterns` in addition to the existing URLs. +Now update the `snippets/urls.py` file slightly, to append a set of `format_suffix_patterns` in addition to the existing URLs. - from django.conf.urls import url + from django.urls import path from rest_framework.urlpatterns import format_suffix_patterns from snippets import views urlpatterns = [ - url(r'^snippets/$', views.snippet_list), - url(r'^snippets/(?P[0-9]+)$', views.snippet_detail), + path('snippets/', views.snippet_list), + path('snippets/', views.snippet_detail), ] urlpatterns = format_suffix_patterns(urlpatterns) @@ -143,7 +141,7 @@ We can get a list of all of the snippets, as before. { "id": 2, "title": "", - "code": "print \"hello, world\"\n", + "code": "print(\"hello, world\")\n", "linenos": false, "language": "python", "style": "friendly" @@ -163,24 +161,24 @@ Or by appending a format suffix: Similarly, we can control the format of the request that we send, using the `Content-Type` header. # POST using form data - http --form POST http://127.0.0.1:8000/snippets/ code="print 123" + http --form POST http://127.0.0.1:8000/snippets/ code="print(123)" { "id": 3, "title": "", - "code": "print 123", + "code": "print(123)", "linenos": false, "language": "python", "style": "friendly" } # POST using JSON - http --json POST http://127.0.0.1:8000/snippets/ code="print 456" + http --json POST http://127.0.0.1:8000/snippets/ code="print(456)" { "id": 4, "title": "", - "code": "print 456", + "code": "print(456)", "linenos": false, "language": "python", "style": "friendly" diff --git a/docs/tutorial/3-class-based-views.md b/docs/tutorial/3-class-based-views.md index f018666f58..e02feaa5ea 100644 --- a/docs/tutorial/3-class-based-views.md +++ b/docs/tutorial/3-class-based-views.md @@ -62,15 +62,15 @@ So far, so good. It looks pretty similar to the previous case, but we've got be That's looking good. Again, it's still pretty similar to the function based view right now. -We'll also need to refactor our `urls.py` slightly now we're using class-based views. +We'll also need to refactor our `snippets/urls.py` slightly now that we're using class-based views. - from django.conf.urls import url + from django.urls import path from rest_framework.urlpatterns import format_suffix_patterns from snippets import views urlpatterns = [ - url(r'^snippets/$', views.SnippetList.as_view()), - url(r'^snippets/(?P[0-9]+)/$', views.SnippetDetail.as_view()), + path('snippets/', views.SnippetList.as_view()), + path('snippets//', views.SnippetDetail.as_view()), ] urlpatterns = format_suffix_patterns(urlpatterns) @@ -146,5 +146,5 @@ Wow, that's pretty concise. We've gotten a huge amount for free, and our code l Next we'll move onto [part 4 of the tutorial][tut-4], where we'll take a look at how we can deal with authentication and permissions for our API. -[dry]: http://en.wikipedia.org/wiki/Don't_repeat_yourself +[dry]: https://en.wikipedia.org/wiki/Don't_repeat_yourself [tut-4]: 4-authentication-and-permissions.md diff --git a/docs/tutorial/4-authentication-and-permissions.md b/docs/tutorial/4-authentication-and-permissions.md index 43ccf91867..6808780fa7 100644 --- a/docs/tutorial/4-authentication-and-permissions.md +++ b/docs/tutorial/4-authentication-and-permissions.md @@ -33,8 +33,8 @@ And now we can add a `.save()` method to our model class: representation of the code snippet. """ lexer = get_lexer_by_name(self.language) - linenos = self.linenos and 'table' or False - options = self.title and {'title': self.title} or {} + linenos = 'table' if self.linenos else False + options = {'title': self.title} if self.title else {} formatter = HtmlFormatter(style=self.style, linenos=linenos, full=True, **options) self.highlighted = highlight(self.code, lexer, formatter) @@ -43,7 +43,7 @@ And now we can add a `.save()` method to our model class: 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. - rm -f tmp.db db.sqlite3 + rm -f db.sqlite3 rm -r snippets/migrations python manage.py makemigrations snippets python manage.py migrate @@ -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. @@ -83,12 +83,12 @@ We'll also add a couple of views to `views.py`. We'd like to just use read-only Make sure to also import the `UserSerializer` class - from snippets.serializers import UserSerializer + from snippets.serializers import UserSerializer -Finally we need to add those views into the API, by referencing them from the URL conf. Add the following to the patterns in `urls.py`. +Finally we need to add those views into the API, by referencing them from the URL conf. Add the following to the patterns in `snippets/urls.py`. - url(r'^users/$', views.UserList.as_view()), - url(r'^users/(?P[0-9]+)/$', views.UserDetail.as_view()), + path('users/', views.UserList.as_view()), + path('users//', views.UserDetail.as_view()), ## Associating Snippets with Users @@ -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 @@ -142,11 +142,10 @@ Add the following import at the top of the file: And, at the end of the file, add a pattern to include the login and logout views for the browsable API. urlpatterns += [ - url(r'^api-auth/', include('rest_framework.urls', - namespace='rest_framework')), + path('api-auth/', include('rest_framework.urls')), ] -The `r'^api-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. In Django 1.9+, REST framework will set the namespace, so you may leave it out. +The `'api-auth/'` part of pattern can actually be whatever URL you want to use. Now if you open up the browser again and refresh the page you'll see a 'Login' link in the top right of the page. If you log in as one of the users you created earlier, you'll be able to create code snippets again. @@ -179,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. @@ -198,7 +197,7 @@ If we're interacting with the API programmatically we need to explicitly provide If we try to create a snippet without authenticating, we'll get an error: - http POST http://127.0.0.1:8000/snippets/ code="print 123" + http POST http://127.0.0.1:8000/snippets/ code="print(123)" { "detail": "Authentication credentials were not provided." @@ -206,13 +205,13 @@ If we try to create a snippet without authenticating, we'll get an error: We can make a successful request by including the username and password of one of the users we created earlier. - http -a tom:password123 POST http://127.0.0.1:8000/snippets/ code="print 789" + http -a admin:password123 POST http://127.0.0.1:8000/snippets/ code="print(789)" { - "id": 5, - "owner": "tom", + "id": 1, + "owner": "admin", "title": "foo", - "code": "print 789", + "code": "print(789)", "linenos": false, "language": "python", "style": "friendly" diff --git a/docs/tutorial/5-relationships-and-hyperlinked-apis.md b/docs/tutorial/5-relationships-and-hyperlinked-apis.md index 9fd61b4149..4cd4e9bbd5 100644 --- a/docs/tutorial/5-relationships-and-hyperlinked-apis.md +++ b/docs/tutorial/5-relationships-and-hyperlinked-apis.md @@ -35,7 +35,7 @@ Instead of using a concrete generic view, we'll use the base class for represent 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() @@ -44,11 +44,11 @@ Instead of using a concrete generic view, we'll use the base class for represent As usual we need to add the new views that we've created in to our URLconf. We'll add a url pattern for our new API root in `snippets/urls.py`: - url(r'^$', views.api_root), + path('', views.api_root), And then add a url pattern for the snippet highlights: - url(r'^snippets/(?P[0-9]+)/highlight/$', views.SnippetHighlight.as_view()), + path('snippets//highlight/', views.SnippetHighlight.as_view()), ## Hyperlinking our API @@ -80,8 +80,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 +89,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. @@ -106,47 +106,42 @@ If we're going to have a hyperlinked API, we need to make sure we name our URL p After adding all those names into our URLconf, our final `snippets/urls.py` file should look like this: - from django.conf.urls import url, include + from django.urls import path from rest_framework.urlpatterns import format_suffix_patterns from snippets import views # API endpoints urlpatterns = format_suffix_patterns([ - url(r'^$', views.api_root), - url(r'^snippets/$', + path('', views.api_root), + path('snippets/', views.SnippetList.as_view(), name='snippet-list'), - url(r'^snippets/(?P[0-9]+)/$', + path('snippets//', views.SnippetDetail.as_view(), name='snippet-detail'), - url(r'^snippets/(?P[0-9]+)/highlight/$', + path('snippets//highlight/', views.SnippetHighlight.as_view(), name='snippet-highlight'), - url(r'^users/$', + path('users/', views.UserList.as_view(), name='user-list'), - url(r'^users/(?P[0-9]+)/$', + path('users//', views.UserDetail.as_view(), name='user-detail') ]) - # Login and logout views for the browsable API - urlpatterns += [ - url(r'^api-auth/', include('rest_framework.urls', - namespace='rest_framework')), - ] - ## Adding pagination The list views for users and code snippets could end up returning quite a lot of instances, so really we'd like to make sure we paginate the results, and allow the API client to step through each of the individual pages. -We can change the default list style to use pagination, by modifying our `tutorial/settings.py` file slightly. Add the following setting: +We can change the default list style to use pagination, by modifying our `tutorial/settings.py` file slightly. Add the following setting: REST_FRAMEWORK = { + 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', 'PAGE_SIZE': 10 } -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. +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. diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index 6189c7771a..11e24448f9 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -25,7 +25,8 @@ Here we've used the `ReadOnlyModelViewSet` class to automatically provide the de Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. - from rest_framework.decorators import detail_route + from rest_framework.decorators import action + from rest_framework.response import Response class SnippetViewSet(viewsets.ModelViewSet): """ @@ -36,10 +37,10 @@ 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] - @detail_route(renderer_classes=[renderers.StaticHTMLRenderer]) + @action(detail=True, renderer_classes=[renderers.StaticHTMLRenderer]) def highlight(self, request, *args, **kwargs): snippet = self.get_object() return Response(snippet.highlighted) @@ -49,18 +50,18 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl This time we've used the `ModelViewSet` class in order to get the complete set of default read and write operations. -Notice that we've also used the `@detail_route` decorator to create a custom action, named `highlight`. This decorator can be used to add any custom endpoints that don't fit into the standard `create`/`update`/`delete` style. +Notice that we've also used the `@action` decorator to create a custom action, named `highlight`. This decorator can be used to add any custom endpoints that don't fit into the standard `create`/`update`/`delete` style. -Custom actions which use the `@detail_route` decorator will respond to `GET` requests by default. We can use the `methods` argument if we wanted an action that responded to `POST` requests. +Custom actions which use the `@action` decorator will respond to `GET` requests by default. We can use the `methods` argument if we wanted an action that responded to `POST` requests. -The URLs for custom actions by default depend on the method name itself. If you want to change the way url should be constructed, you can include url_path as a decorator keyword argument. +The URLs for custom actions by default depend on the method name itself. If you want to change the way url should be constructed, you can include `url_path` as a decorator keyword argument. ## Binding ViewSets to URLs explicitly The handler methods only get bound to the actions when we define the URLConf. To see what's going on under the hood let's first explicitly create a set of views from our ViewSets. -In the `urls.py` file we bind our `ViewSet` classes into a set of concrete views. +In the `snippets/urls.py` file we bind our `ViewSet` classes into a set of concrete views. from snippets.views import SnippetViewSet, UserViewSet, api_root from rest_framework import renderers @@ -90,23 +91,23 @@ Notice how we're creating multiple views from each `ViewSet` class, by binding t Now that we've bound our resources into concrete views, we can register the views with the URL conf as usual. urlpatterns = format_suffix_patterns([ - url(r'^$', api_root), - url(r'^snippets/$', snippet_list, name='snippet-list'), - url(r'^snippets/(?P[0-9]+)/$', snippet_detail, name='snippet-detail'), - url(r'^snippets/(?P[0-9]+)/highlight/$', snippet_highlight, name='snippet-highlight'), - url(r'^users/$', user_list, name='user-list'), - url(r'^users/(?P[0-9]+)/$', user_detail, name='user-detail') + path('', api_root), + path('snippets/', snippet_list, name='snippet-list'), + path('snippets//', snippet_detail, name='snippet-detail'), + path('snippets//highlight/', snippet_highlight, name='snippet-highlight'), + path('users/', user_list, name='user-list'), + path('users//', user_detail, name='user-detail') ]) ## Using Routers Because we're using `ViewSet` classes rather than `View` classes, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a `Router` class. All we need to do is register the appropriate view sets with a router, and let it do the rest. -Here's our re-wired `urls.py` file. +Here's our re-wired `snippets/urls.py` file. - from django.conf.urls import url, include - from snippets import views + from django.urls import path, include from rest_framework.routers import DefaultRouter + from snippets import views # Create a router and register our viewsets with it. router = DefaultRouter() @@ -114,10 +115,8 @@ Here's our re-wired `urls.py` file. router.register(r'users', views.UserViewSet) # The API URLs are now determined automatically by the router. - # Additionally, we include the 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)), ] Registering the viewsets with the router is similar to providing a urlpattern. We include two arguments - the URL prefix for the views, and the viewset itself. @@ -129,8 +128,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 96fed27678..ee54816dc4 100644 --- a/docs/tutorial/quickstart.md +++ b/docs/tutorial/quickstart.md @@ -10,29 +10,53 @@ 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 # Set up a new project with a single application - django-admin.py startproject tutorial . # Note the trailing '.' character + django-admin startproject tutorial . # Note the trailing '.' character cd tutorial - django-admin.py startapp quickstart + django-admin startapp quickstart cd .. +The project layout should look like: + + $ pwd + /tutorial + $ find . + . + ./manage.py + ./tutorial + ./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/tests.py + ./tutorial/quickstart/views.py + ./tutorial/settings.py + ./tutorial/urls.py + ./tutorial/wsgi.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). + 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. - python manage.py createsuperuser + python manage.py createsuperuser --email admin@example.com --username admin -Once you've set up a database and initial user created and ready to go, open up the app's directory and we'll get coding... +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... ## Serializers @@ -45,15 +69,15 @@ First up we're going to define some serializers. Let's create a new module named 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. +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. ## Views @@ -87,7 +111,7 @@ We can easily break these down into individual views if we need to, but using vi Okay, now let's wire up the API URLs. On to `tutorial/urls.py`... - from django.conf.urls import url, include + from django.urls import include, path from rest_framework import routers from tutorial.quickstart import views @@ -98,8 +122,8 @@ Okay, now let's wire up the API URLs. On to `tutorial/urls.py`... # 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')) ] Because we're using viewsets instead of views, we can automatically generate the URL conf for our API, by simply registering the viewsets with a router class. @@ -108,19 +132,22 @@ Again, if we need more control over the API URLs we can simply drop down to usin Finally, we're including default login and logout views for use with the browsable API. That's optional, but useful if your API requires authentication and you want to use the browsable API. +## 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 -We'd also like to set a few global settings. We'd like to turn on pagination, and we want our API to only be accessible to admin users. The settings module will be in `tutorial/settings.py` +Add `'rest_framework'` to `INSTALLED_APPS`. The settings module will be in `tutorial/settings.py` - INSTALLED_APPS = ( + INSTALLED_APPS = [ ... 'rest_framework', - ) - - REST_FRAMEWORK = { - 'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',), - 'PAGE_SIZE': 10 - } + ] Okay, we're done. @@ -192,7 +219,6 @@ Great, that was easy! If you want to get a more in depth understanding of how REST framework fits together head on over to [the tutorial][tutorial], or start browsing the [API guide][guide]. -[readme-example-api]: ../#example [image]: ../img/quickstart.png [tutorial]: 1-serialization.md [guide]: ../#api-guide diff --git a/docs_theme/404.html b/docs_theme/404.html index ce520a7c10..a89c0a418d 100644 --- a/docs_theme/404.html +++ b/docs_theme/404.html @@ -1,9 +1,9 @@ -{% extends "base.html" %} +{% extends "main.html" %} {% block content %}

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/bootstrap-responsive.css b/docs_theme/css/bootstrap-responsive.css old mode 100755 new mode 100644 index a8caf451d9..ec0b51947d --- a/docs_theme/css/bootstrap-responsive.css +++ b/docs_theme/css/bootstrap-responsive.css @@ -3,7 +3,7 @@ * * Copyright 2012 Twitter, Inc * Licensed under the Apache License v2.0 - * http://www.apache.org/licenses/LICENSE-2.0 + * https://www.apache.org/licenses/LICENSE-2.0 * * Designed and built with all the love in the world @twitter by @mdo and @fat. */ diff --git a/docs_theme/css/bootstrap.css b/docs_theme/css/bootstrap.css old mode 100755 new mode 100644 index 53df685954..a48bbbecf9 --- a/docs_theme/css/bootstrap.css +++ b/docs_theme/css/bootstrap.css @@ -3,7 +3,7 @@ * * Copyright 2012 Twitter, Inc * Licensed under the Apache License v2.0 - * http://www.apache.org/licenses/LICENSE-2.0 + * https://www.apache.org/licenses/LICENSE-2.0 * * Designed and built with all the love in the world @twitter by @mdo and @fat. */ diff --git a/docs_theme/css/default.css b/docs_theme/css/default.css index 192e86860f..bb17a3a115 100644 --- a/docs_theme/css/default.css +++ b/docs_theme/css/default.css @@ -160,9 +160,19 @@ body, .navbar .navbar-inner .container-fluid{ margin: 0 auto; } -body{ - background: url("../img/grid.png") repeat-x; - background-attachment: fixed; +/* Replacement for `body { background-attachment: fixed; }`, which + has performance issues when scrolling on large displays. */ +body::before { + content: ' '; + position: fixed; + width: 100%; + height: 100%; + top: 0; + left: 0; + background-color: #f8f8f8; + background: url(../img/grid.png) repeat-x; + will-change: transform; + z-index: -1; } @@ -417,3 +427,8 @@ ul.sponsor { .toclink { color: #333; } + +.book-cover img { + margin: 0 !important; + display: inline-block !important; +} diff --git a/docs_theme/js/bootstrap-2.1.1-min.js b/docs_theme/js/bootstrap-2.1.1-min.js old mode 100755 new mode 100644 diff --git a/docs_theme/js/theme.js b/docs_theme/js/theme.js index ddbd9c9053..0918ae85dd 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/base.html b/docs_theme/main.html similarity index 83% rename from docs_theme/base.html rename to docs_theme/main.html index 6cb929d1c2..21e9171a2a 100644 --- a/docs_theme/base.html +++ b/docs_theme/main.html @@ -4,11 +4,11 @@ - {% if page_title %}{{ page_title }} - {% endif %}{{ site_name }} + {% if page.title %}{{ page.title }} - {% endif %}{{ config.site_name }} - + - + @@ -51,7 +51,7 @@ } - +
{% include "nav.html" %} @@ -83,14 +83,14 @@

Documentation search

    - {% if current_page and current_page.is_homepage %} + {% if page and page.is_homepage %}
  • Django REST framework
    • {% endif %} - {% for toc_item in toc %} -
  • + {% for toc_item in page.toc %} +
  • {{ toc_item.title }}
    • @@ -112,15 +112,15 @@

    Documentation search

    {% block content %} - {% if meta.source %} - {% for filename in meta.source %} - + {% if page.meta.source %} + {% for filename in page.meta.source %} + {{ filename }} {% endfor %} {% endif %} - {{ content }} + {{ page.content }} {% endblock %}
    @@ -138,14 +138,17 @@

    Documentation search

    + - - - + + {% for path in config.extra_javascript %} + + {% endfor %} + ",rE:!0,sL:""}},s,{cN:"pi",b:/<\?\w+/,e:/\?>/,r:10},{cN:"tag",b:"",c:[{cN:"title",b:/[^ \/><\n\t]+/,r:0},c]}]}});hljs.registerLanguage("autohotkey",function(e){var r={cN:"escape",b:"`[\\s\\S]"},c=e.C(";","$",{r:0}),n=[{cN:"built_in",b:"A_[a-zA-Z0-9]+"},{cN:"built_in",bK:"ComSpec Clipboard ClipboardAll ErrorLevel"}];return{cI:!0,k:{keyword:"Break Continue Else Gosub If Loop Return While",literal:"A true false NOT AND OR"},c:n.concat([r,e.inherit(e.QSM,{c:[r]}),c,{cN:"number",b:e.NR,r:0},{cN:"var_expand",b:"%",e:"%",i:"\\n",c:[r]},{cN:"label",c:[r],v:[{b:'^[^\\n";]+::(?!=)'},{b:'^[^\\n";]+:(?!=)',r:0}]},{b:",\\s*,",r:10}])}});hljs.registerLanguage("r",function(e){var r="([a-zA-Z]|\\.[a-zA-Z.])[a-zA-Z0-9._]*";return{c:[e.HCM,{b:r,l:r,k:{keyword:"function if in break next repeat else for return switch while try tryCatch stop warning require library attach detach source setMethod setGeneric setGroupGeneric setClass ...",literal:"NULL NA TRUE FALSE T F Inf NaN NA_integer_|10 NA_real_|10 NA_character_|10 NA_complex_|10"},r:0},{cN:"number",b:"0[xX][0-9a-fA-F]+[Li]?\\b",r:0},{cN:"number",b:"\\d+(?:[eE][+\\-]?\\d*)?L\\b",r:0},{cN:"number",b:"\\d+\\.(?!\\d)(?:i\\b)?",r:0},{cN:"number",b:"\\d+(?:\\.\\d*)?(?:[eE][+\\-]?\\d*)?i?\\b",r:0},{cN:"number",b:"\\.\\d+(?:[eE][+\\-]?\\d*)?i?\\b",r:0},{b:"`",e:"`",r:0},{cN:"string",c:[e.BE],v:[{b:'"',e:'"'},{b:"'",e:"'"}]}]}});hljs.registerLanguage("cs",function(e){var r="abstract as base bool break byte case catch char checked const continue decimal dynamic default delegate do double else enum event explicit extern false finally fixed float for foreach goto if implicit in int interface internal is lock long null when object operator out override params private protected public readonly ref sbyte sealed short sizeof stackalloc static string struct switch this true try typeof uint ulong unchecked unsafe ushort using virtual volatile void while async protected public private internal ascending descending from get group into join let orderby partial select set value var where yield",t=e.IR+"(<"+e.IR+">)?";return{aliases:["csharp"],k:r,i:/::/,c:[e.C("///","$",{rB:!0,c:[{cN:"xmlDocTag",v:[{b:"///",r:0},{b:""},{b:""}]}]}),e.CLCM,e.CBCM,{cN:"preprocessor",b:"#",e:"$",k:"if else elif endif define undef warning error line region endregion pragma checksum"},{cN:"string",b:'@"',e:'"',c:[{b:'""'}]},e.ASM,e.QSM,e.CNM,{bK:"class namespace interface",e:/[{;=]/,i:/[^\s:]/,c:[e.TM,e.CLCM,e.CBCM]},{bK:"new return throw await",r:0},{cN:"function",b:"("+t+"\\s+)+"+e.IR+"\\s*\\(",rB:!0,e:/[{;=]/,eE:!0,k:r,c:[{b:e.IR+"\\s*\\(",rB:!0,c:[e.TM],r:0},{cN:"params",b:/\(/,e:/\)/,k:r,r:0,c:[e.ASM,e.QSM,e.CNM,e.CBCM]},e.CLCM,e.CBCM]}]}});hljs.registerLanguage("nsis",function(e){var t={cN:"symbol",b:"\\$(ADMINTOOLS|APPDATA|CDBURN_AREA|CMDLINE|COMMONFILES32|COMMONFILES64|COMMONFILES|COOKIES|DESKTOP|DOCUMENTS|EXEDIR|EXEFILE|EXEPATH|FAVORITES|FONTS|HISTORY|HWNDPARENT|INSTDIR|INTERNET_CACHE|LANGUAGE|LOCALAPPDATA|MUSIC|NETHOOD|OUTDIR|PICTURES|PLUGINSDIR|PRINTHOOD|PROFILE|PROGRAMFILES32|PROGRAMFILES64|PROGRAMFILES|QUICKLAUNCH|RECENT|RESOURCES_LOCALIZED|RESOURCES|SENDTO|SMPROGRAMS|SMSTARTUP|STARTMENU|SYSDIR|TEMP|TEMPLATES|VIDEOS|WINDIR)"},n={cN:"constant",b:"\\$+{[a-zA-Z0-9_]+}"},i={cN:"variable",b:"\\$+[a-zA-Z0-9_]+",i:"\\(\\){}"},r={cN:"constant",b:"\\$+\\([a-zA-Z0-9_]+\\)"},o={cN:"params",b:"(ARCHIVE|FILE_ATTRIBUTE_ARCHIVE|FILE_ATTRIBUTE_NORMAL|FILE_ATTRIBUTE_OFFLINE|FILE_ATTRIBUTE_READONLY|FILE_ATTRIBUTE_SYSTEM|FILE_ATTRIBUTE_TEMPORARY|HKCR|HKCU|HKDD|HKEY_CLASSES_ROOT|HKEY_CURRENT_CONFIG|HKEY_CURRENT_USER|HKEY_DYN_DATA|HKEY_LOCAL_MACHINE|HKEY_PERFORMANCE_DATA|HKEY_USERS|HKLM|HKPD|HKU|IDABORT|IDCANCEL|IDIGNORE|IDNO|IDOK|IDRETRY|IDYES|MB_ABORTRETRYIGNORE|MB_DEFBUTTON1|MB_DEFBUTTON2|MB_DEFBUTTON3|MB_DEFBUTTON4|MB_ICONEXCLAMATION|MB_ICONINFORMATION|MB_ICONQUESTION|MB_ICONSTOP|MB_OK|MB_OKCANCEL|MB_RETRYCANCEL|MB_RIGHT|MB_RTLREADING|MB_SETFOREGROUND|MB_TOPMOST|MB_USERICON|MB_YESNO|NORMAL|OFFLINE|READONLY|SHCTX|SHELL_CONTEXT|SYSTEM|TEMPORARY)"},l={cN:"constant",b:"\\!(addincludedir|addplugindir|appendfile|cd|define|delfile|echo|else|endif|error|execute|finalize|getdllversionsystem|ifdef|ifmacrodef|ifmacrondef|ifndef|if|include|insertmacro|macroend|macro|makensis|packhdr|searchparse|searchreplace|tempfile|undef|verbose|warning)"};return{cI:!1,k:{keyword:"Abort AddBrandingImage AddSize AllowRootDirInstall AllowSkipFiles AutoCloseWindow BGFont BGGradient BrandingText BringToFront Call CallInstDLL Caption ChangeUI CheckBitmap ClearErrors CompletedText ComponentText CopyFiles CRCCheck CreateDirectory CreateFont CreateShortCut Delete DeleteINISec DeleteINIStr DeleteRegKey DeleteRegValue DetailPrint DetailsButtonText DirText DirVar DirVerify EnableWindow EnumRegKey EnumRegValue Exch Exec ExecShell ExecWait ExpandEnvStrings File FileBufSize FileClose FileErrorText FileOpen FileRead FileReadByte FileReadUTF16LE FileReadWord FileSeek FileWrite FileWriteByte FileWriteUTF16LE FileWriteWord FindClose FindFirst FindNext FindWindow FlushINI FunctionEnd GetCurInstType GetCurrentAddress GetDlgItem GetDLLVersion GetDLLVersionLocal GetErrorLevel GetFileTime GetFileTimeLocal GetFullPathName GetFunctionAddress GetInstDirError GetLabelAddress GetTempFileName Goto HideWindow Icon IfAbort IfErrors IfFileExists IfRebootFlag IfSilent InitPluginsDir InstallButtonText InstallColors InstallDir InstallDirRegKey InstProgressFlags InstType InstTypeGetText InstTypeSetText IntCmp IntCmpU IntFmt IntOp IsWindow LangString LicenseBkColor LicenseData LicenseForceSelection LicenseLangString LicenseText LoadLanguageFile LockWindow LogSet LogText ManifestDPIAware ManifestSupportedOS MessageBox MiscButtonText Name Nop OutFile Page PageCallbacks PageExEnd Pop Push Quit ReadEnvStr ReadINIStr ReadRegDWORD ReadRegStr Reboot RegDLL Rename RequestExecutionLevel ReserveFile Return RMDir SearchPath SectionEnd SectionGetFlags SectionGetInstTypes SectionGetSize SectionGetText SectionGroupEnd SectionIn SectionSetFlags SectionSetInstTypes SectionSetSize SectionSetText SendMessage SetAutoClose SetBrandingImage SetCompress SetCompressor SetCompressorDictSize SetCtlColors SetCurInstType SetDatablockOptimize SetDateSave SetDetailsPrint SetDetailsView SetErrorLevel SetErrors SetFileAttributes SetFont SetOutPath SetOverwrite SetPluginUnload SetRebootFlag SetRegView SetShellVarContext SetSilent ShowInstDetails ShowUninstDetails ShowWindow SilentInstall SilentUnInstall Sleep SpaceTexts StrCmp StrCmpS StrCpy StrLen SubCaption SubSectionEnd Unicode UninstallButtonText UninstallCaption UninstallIcon UninstallSubCaption UninstallText UninstPage UnRegDLL Var VIAddVersionKey VIFileVersion VIProductVersion WindowIcon WriteINIStr WriteRegBin WriteRegDWORD WriteRegExpandStr WriteRegStr WriteUninstaller XPStyle",literal:"admin all auto both colored current false force hide highest lastused leave listonly none normal notset off on open print show silent silentlog smooth textonly true user "},c:[e.HCM,e.CBCM,{cN:"string",b:'"',e:'"',i:"\\n",c:[{cN:"symbol",b:"\\$(\\\\(n|r|t)|\\$)"},t,n,i,r]},e.C(";","$",{r:0}),{cN:"function",bK:"Function PageEx Section SectionGroup SubSection",e:"$"},l,n,i,r,o,e.NM,{cN:"literal",b:e.IR+"::"+e.IR}]}});hljs.registerLanguage("less",function(e){var r="[\\w-]+",t="("+r+"|@{"+r+"})",a=[],c=[],n=function(e){return{cN:"string",b:"~?"+e+".*?"+e}},i=function(e,r,t){return{cN:e,b:r,r:t}},s=function(r,t,a){return e.inherit({cN:r,b:t+"\\(",e:"\\(",rB:!0,eE:!0,r:0},a)},b={b:"\\(",e:"\\)",c:c,r:0};c.push(e.CLCM,e.CBCM,n("'"),n('"'),e.CSSNM,i("hexcolor","#[0-9A-Fa-f]+\\b"),s("function","(url|data-uri)",{starts:{cN:"string",e:"[\\)\\n]",eE:!0}}),s("function",r),b,i("variable","@@?"+r,10),i("variable","@{"+r+"}"),i("built_in","~?`[^`]*?`"),{cN:"attribute",b:r+"\\s*:",e:":",rB:!0,eE:!0});var o=c.concat({b:"{",e:"}",c:a}),u={bK:"when",eW:!0,c:[{bK:"and not"}].concat(c)},C={cN:"attribute",b:t,e:":",eE:!0,c:[e.CLCM,e.CBCM],i:/\S/,starts:{e:"[;}]",rE:!0,c:c,i:"[<=$]"}},l={cN:"at_rule",b:"@(import|media|charset|font-face|(-[a-z]+-)?keyframes|supports|document|namespace|page|viewport|host)\\b",starts:{e:"[;{}]",rE:!0,c:c,r:0}},d={cN:"variable",v:[{b:"@"+r+"\\s*:",r:15},{b:"@"+r}],starts:{e:"[;}]",rE:!0,c:o}},p={v:[{b:"[\\.#:&\\[]",e:"[;{}]"},{b:t+"[^;]*{",e:"{"}],rB:!0,rE:!0,i:"[<='$\"]",c:[e.CLCM,e.CBCM,u,i("keyword","all\\b"),i("variable","@{"+r+"}"),i("tag",t+"%?",0),i("id","#"+t),i("class","\\."+t,0),i("keyword","&",0),s("pseudo",":not"),s("keyword",":extend"),i("pseudo","::?"+t),{cN:"attr_selector",b:"\\[",e:"\\]"},{b:"\\(",e:"\\)",c:o},{b:"!important"}]};return a.push(e.CLCM,e.CBCM,l,d,p,C),{cI:!0,i:"[=>'/<($\"]",c:a}});hljs.registerLanguage("pf",function(t){var o={cN:"variable",b:/\$[\w\d#@][\w\d_]*/},e={cN:"variable",b://};return{aliases:["pf.conf"],l:/[a-z0-9_<>-]+/,k:{built_in:"block match pass load anchor|5 antispoof|10 set table",keyword:"in out log quick on rdomain inet inet6 proto from port os to routeallow-opts divert-packet divert-reply divert-to flags group icmp-typeicmp6-type label once probability recieved-on rtable prio queuetos tag tagged user keep fragment for os dropaf-to|10 binat-to|10 nat-to|10 rdr-to|10 bitmask least-stats random round-robinsource-hash static-portdup-to reply-to route-toparent bandwidth default min max qlimitblock-policy debug fingerprints hostid limit loginterface optimizationreassemble ruleset-optimization basic none profile skip state-defaultsstate-policy timeoutconst counters persistno modulate synproxy state|5 floating if-bound no-sync pflow|10 sloppysource-track global rule max-src-nodes max-src-states max-src-connmax-src-conn-rate overload flushscrub|5 max-mss min-ttl no-df|10 random-id",literal:"all any no-route self urpf-failed egress|5 unknown"},c:[t.HCM,t.NM,t.QSM,o,e]}});hljs.registerLanguage("lasso",function(e){var r="[a-zA-Z_][a-zA-Z0-9_.]*",a="<\\?(lasso(script)?|=)",t="\\]|\\?>",s={literal:"true false none minimal full all void and or not bw nbw ew new cn ncn lt lte gt gte eq neq rx nrx ft",built_in:"array date decimal duration integer map pair string tag xml null boolean bytes keyword list locale queue set stack staticarray local var variable global data self inherited",keyword:"error_code error_msg error_pop error_push error_reset cache database_names database_schemanames database_tablenames define_tag define_type email_batch encode_set html_comment handle handle_error header if inline iterate ljax_target link link_currentaction link_currentgroup link_currentrecord link_detail link_firstgroup link_firstrecord link_lastgroup link_lastrecord link_nextgroup link_nextrecord link_prevgroup link_prevrecord log loop namespace_using output_none portal private protect records referer referrer repeating resultset rows search_args search_arguments select sort_args sort_arguments thread_atomic value_list while abort case else if_empty if_false if_null if_true loop_abort loop_continue loop_count params params_up return return_value run_children soap_definetag soap_lastrequest soap_lastresponse tag_name ascending average by define descending do equals frozen group handle_failure import in into join let match max min on order parent protected provide public require returnhome skip split_thread sum take thread to trait type where with yield yieldhome"},n=e.C("",{r:0}),o={cN:"preprocessor",b:"\\[noprocess\\]",starts:{cN:"markup",e:"\\[/noprocess\\]",rE:!0,c:[n]}},i={cN:"preprocessor",b:"\\[/noprocess|"+a},l={cN:"variable",b:"'"+r+"'"},c=[e.CLCM,{cN:"javadoc",b:"/\\*\\*!",e:"\\*/",c:[e.PWM]},e.CBCM,e.inherit(e.CNM,{b:e.CNR+"|(-?infinity|nan)\\b"}),e.inherit(e.ASM,{i:null}),e.inherit(e.QSM,{i:null}),{cN:"string",b:"`",e:"`"},{cN:"variable",v:[{b:"[#$]"+r},{b:"#",e:"\\d+",i:"\\W"}]},{cN:"tag",b:"::\\s*",e:r,i:"\\W"},{cN:"attribute",v:[{b:"-"+e.UIR,r:0},{b:"(\\.\\.\\.)"}]},{cN:"subst",v:[{b:"->\\s*",c:[l]},{b:":=|/(?!\\w)=?|[-+*%=<>&|!?\\\\]+",r:0}]},{cN:"built_in",b:"\\.\\.?\\s*",r:0,c:[l]},{cN:"class",bK:"define",rE:!0,e:"\\(|=>",c:[e.inherit(e.TM,{b:e.UIR+"(=(?!>))?"})]}];return{aliases:["ls","lassoscript"],cI:!0,l:r+"|&[lg]t;",k:s,c:[{cN:"preprocessor",b:t,r:0,starts:{cN:"markup",e:"\\[|"+a,rE:!0,r:0,c:[n]}},o,i,{cN:"preprocessor",b:"\\[no_square_brackets",starts:{e:"\\[/no_square_brackets\\]",l:r+"|&[lg]t;",k:s,c:[{cN:"preprocessor",b:t,r:0,starts:{cN:"markup",e:"\\[noprocess\\]|"+a,rE:!0,c:[n]}},o,i].concat(c)}},{cN:"preprocessor",b:"\\[",r:0},{cN:"shebang",b:"^#!.+lasso9\\b",r:10}].concat(c)}});hljs.registerLanguage("prolog",function(c){var r={cN:"atom",b:/[a-z][A-Za-z0-9_]*/,r:0},b={cN:"name",v:[{b:/[A-Z][a-zA-Z0-9_]*/},{b:/_[A-Za-z0-9_]*/}],r:0},a={b:/\(/,e:/\)/,r:0},e={b:/\[/,e:/\]/},n={cN:"comment",b:/%/,e:/$/,c:[c.PWM]},t={cN:"string",b:/`/,e:/`/,c:[c.BE]},g={cN:"string",b:/0\'(\\\'|.)/},N={cN:"string",b:/0\'\\s/},o={b:/:-/},s=[r,b,a,o,e,n,c.CBCM,c.QSM,c.ASM,t,g,N,c.CNM];return a.c=s,e.c=s,{c:s.concat([{b:/\.$/}])}});hljs.registerLanguage("oxygene",function(e){var r="abstract add and array as asc aspect assembly async begin break block by case class concat const copy constructor continue create default delegate desc distinct div do downto dynamic each else empty end ensure enum equals event except exit extension external false final finalize finalizer finally flags for forward from function future global group has if implementation implements implies in index inherited inline interface into invariants is iterator join locked locking loop matching method mod module namespace nested new nil not notify nullable of old on operator or order out override parallel params partial pinned private procedure property protected public queryable raise read readonly record reintroduce remove repeat require result reverse sealed select self sequence set shl shr skip static step soft take then to true try tuple type union unit unsafe until uses using var virtual raises volatile where while with write xor yield await mapped deprecated stdcall cdecl pascal register safecall overload library platform reference packed strict published autoreleasepool selector strong weak unretained",t=e.C("{","}",{r:0}),a=e.C("\\(\\*","\\*\\)",{r:10}),n={cN:"string",b:"'",e:"'",c:[{b:"''"}]},o={cN:"string",b:"(#\\d+)+"},i={cN:"function",bK:"function constructor destructor procedure method",e:"[:;]",k:"function constructor|10 destructor|10 procedure|10 method|10",c:[e.TM,{cN:"params",b:"\\(",e:"\\)",k:r,c:[n,o]},t,a]};return{cI:!0,k:r,i:'("|\\$[G-Zg-z]|\\/\\*||->)',c:[t,a,e.CLCM,n,o,e.NM,i,{cN:"class",b:"=\\bclass\\b",e:"end;",k:r,c:[n,o,t,a,e.CLCM,i]}]}});hljs.registerLanguage("applescript",function(e){var t=e.inherit(e.QSM,{i:""}),r={cN:"params",b:"\\(",e:"\\)",c:["self",e.CNM,t]},o=e.C("--","$"),n=e.C("\\(\\*","\\*\\)",{c:["self",o]}),a=[o,n,e.HCM];return{aliases:["osascript"],k:{keyword:"about above after against and around as at back before beginning behind below beneath beside between but by considering contain contains continue copy div does eighth else end equal equals error every exit fifth first for fourth from front get given global if ignoring in into is it its last local me middle mod my ninth not of on onto or over prop property put ref reference repeat returning script second set seventh since sixth some tell tenth that the|0 then third through thru timeout times to transaction try until where while whose with without",constant:"AppleScript false linefeed return pi quote result space tab true",type:"alias application boolean class constant date file integer list number real record string text",command:"activate beep count delay launch log offset read round run say summarize write",property:"character characters contents day frontmost id item length month name paragraph paragraphs rest reverse running time version weekday word words year"},c:[t,e.CNM,{cN:"type",b:"\\bPOSIX file\\b"},{cN:"command",b:"\\b(clipboard info|the clipboard|info for|list (disks|folder)|mount volume|path to|(close|open for) access|(get|set) eof|current date|do shell script|get volume settings|random number|set volume|system attribute|system info|time to GMT|(load|run|store) script|scripting components|ASCII (character|number)|localized string|choose (application|color|file|file name|folder|from list|remote application|URL)|display (alert|dialog))\\b|^\\s*return\\b"},{cN:"constant",b:"\\b(text item delimiters|current application|missing value)\\b"},{cN:"keyword",b:"\\b(apart from|aside from|instead of|out of|greater than|isn't|(doesn't|does not) (equal|come before|come after|contain)|(greater|less) than( or equal)?|(starts?|ends|begins?) with|contained by|comes (before|after)|a (ref|reference))\\b"},{cN:"property",b:"\\b(POSIX path|(date|time) string|quoted form)\\b"},{cN:"function_start",bK:"on",i:"[${=;\\n]",c:[e.UTM,r]}].concat(a),i:"//|->|=>"}});hljs.registerLanguage("makefile",function(e){var a={cN:"variable",b:/\$\(/,e:/\)/,c:[e.BE]};return{aliases:["mk","mak"],c:[e.HCM,{b:/^\w+\s*\W*=/,rB:!0,r:0,starts:{cN:"constant",e:/\s*\W*=/,eE:!0,starts:{e:/$/,r:0,c:[a]}}},{cN:"title",b:/^[\w]+:\s*$/},{cN:"phony",b:/^\.PHONY:/,e:/$/,k:".PHONY",l:/[\.\w]+/},{b:/^\t+/,e:/$/,r:0,c:[e.QSM,a]}]}});hljs.registerLanguage("dust",function(e){var a="if eq ne lt lte gt gte select default math sep";return{aliases:["dst"],cI:!0,sL:"xml",subLanguageMode:"continuous",c:[{cN:"expression",b:"{",e:"}",r:0,c:[{cN:"begin-block",b:"#[a-zA-Z- .]+",k:a},{cN:"string",b:'"',e:'"'},{cN:"end-block",b:"\\/[a-zA-Z- .]+",k:a},{cN:"variable",b:"[a-zA-Z-.]+",k:a,r:0}]}]}});hljs.registerLanguage("clojure-repl",function(e){return{c:[{cN:"prompt",b:/^([\w.-]+|\s*#_)=>/,starts:{e:/$/,sL:"clojure",subLanguageMode:"continuous"}}]}});hljs.registerLanguage("dart",function(e){var t={cN:"subst",b:"\\$\\{",e:"}",k:"true false null this is new super"},r={cN:"string",v:[{b:"r'''",e:"'''"},{b:'r"""',e:'"""'},{b:"r'",e:"'",i:"\\n"},{b:'r"',e:'"',i:"\\n"},{b:"'''",e:"'''",c:[e.BE,t]},{b:'"""',e:'"""',c:[e.BE,t]},{b:"'",e:"'",i:"\\n",c:[e.BE,t]},{b:'"',e:'"',i:"\\n",c:[e.BE,t]}]};t.c=[e.CNM,r];var n={keyword:"assert break case catch class const continue default do else enum extends false final finally for if in is new null rethrow return super switch this throw true try var void while with",literal:"abstract as dynamic export external factory get implements import library operator part set static typedef",built_in:"print Comparable DateTime Duration Function Iterable Iterator List Map Match Null Object Pattern RegExp Set Stopwatch String StringBuffer StringSink Symbol Type Uri bool double int num document window querySelector querySelectorAll Element ElementList"};return{k:n,c:[r,{cN:"dartdoc",b:"/\\*\\*",e:"\\*/",sL:"markdown",subLanguageMode:"continuous"},{cN:"dartdoc",b:"///",e:"$",sL:"markdown",subLanguageMode:"continuous"},e.CLCM,e.CBCM,{cN:"class",bK:"class interface",e:"{",eE:!0,c:[{bK:"extends implements"},e.UTM]},e.CNM,{cN:"annotation",b:"@[A-Za-z]+"},{b:"=>"}]}}); \ No newline at end of file diff --git a/rest_framework/static/rest_framework/docs/js/jquery.json-view.min.js b/rest_framework/static/rest_framework/docs/js/jquery.json-view.min.js new file mode 100644 index 0000000000..ce3a60435e --- /dev/null +++ b/rest_framework/static/rest_framework/docs/js/jquery.json-view.min.js @@ -0,0 +1,7 @@ +/** + * jquery.json-view - jQuery collapsible JSON plugin + * @version v1.0.0 + * @link http://github.com/bazh/jquery.json-view + * @license MIT + */ +!function(e){"use strict";var n=function(n){var a=e("",{"class":"collapser",on:{click:function(){var n=e(this);n.toggleClass("collapsed");var a=n.parent().children(".block"),p=a.children("ul");n.hasClass("collapsed")?(p.hide(),a.children(".dots, .comments").show()):(p.show(),a.children(".dots, .comments").hide())}}});return n&&a.addClass("collapsed"),a},a=function(a,p){var t=e.extend({},{nl2br:!0},p),r=function(e){return e.toString()?e.toString().replace(/&/g,"&").replace(/"/g,""").replace(//g,">"):""},s=function(n,a){return e("",{"class":a,html:r(n)})},l=function(a,p){switch(e.type(a)){case"object":p||(p=0);var c=e("",{"class":"block"}),d=Object.keys(a).length;if(!d)return c.append(s("{","b")).append(" ").append(s("}","b"));c.append(s("{","b"));var i=e("
',trigger:"hover focus",title:"",delay:0,html:!1,container:!1,viewport:{selector:"body",padding:0},sanitize:!0,sanitizeFn:null,whiteList:t},m.prototype.init=function(t,e,i){if(this.enabled=!0,this.type=t,this.$element=g(e),this.options=this.getOptions(i),this.$viewport=this.options.viewport&&g(document).find(g.isFunction(this.options.viewport)?this.options.viewport.call(this,this.$element):this.options.viewport.selector||this.options.viewport),this.inState={click:!1,hover:!1,focus:!1},this.$element[0]instanceof document.constructor&&!this.options.selector)throw new Error("`selector` option must be specified when initializing "+this.type+" on the window.document object!");for(var o=this.options.trigger.split(" "),n=o.length;n--;){var s=o[n];if("click"==s)this.$element.on("click."+this.type,this.options.selector,g.proxy(this.toggle,this));else if("manual"!=s){var a="hover"==s?"mouseenter":"focusin",r="hover"==s?"mouseleave":"focusout";this.$element.on(a+"."+this.type,this.options.selector,g.proxy(this.enter,this)),this.$element.on(r+"."+this.type,this.options.selector,g.proxy(this.leave,this))}}this.options.selector?this._options=g.extend({},this.options,{trigger:"manual",selector:""}):this.fixTitle()},m.prototype.getDefaults=function(){return m.DEFAULTS},m.prototype.getOptions=function(t){var e=this.$element.data();for(var i in e)e.hasOwnProperty(i)&&-1!==g.inArray(i,o)&&delete e[i];return(t=g.extend({},this.getDefaults(),e,t)).delay&&"number"==typeof t.delay&&(t.delay={show:t.delay,hide:t.delay}),t.sanitize&&(t.template=n(t.template,t.whiteList,t.sanitizeFn)),t},m.prototype.getDelegateOptions=function(){var i={},o=this.getDefaults();return this._options&&g.each(this._options,function(t,e){o[t]!=e&&(i[t]=e)}),i},m.prototype.enter=function(t){var e=t instanceof this.constructor?t:g(t.currentTarget).data("bs."+this.type);if(e||(e=new this.constructor(t.currentTarget,this.getDelegateOptions()),g(t.currentTarget).data("bs."+this.type,e)),t instanceof g.Event&&(e.inState["focusin"==t.type?"focus":"hover"]=!0),e.tip().hasClass("in")||"in"==e.hoverState)e.hoverState="in";else{if(clearTimeout(e.timeout),e.hoverState="in",!e.options.delay||!e.options.delay.show)return e.show();e.timeout=setTimeout(function(){"in"==e.hoverState&&e.show()},e.options.delay.show)}},m.prototype.isInStateTrue=function(){for(var t in this.inState)if(this.inState[t])return!0;return!1},m.prototype.leave=function(t){var e=t instanceof this.constructor?t:g(t.currentTarget).data("bs."+this.type);if(e||(e=new this.constructor(t.currentTarget,this.getDelegateOptions()),g(t.currentTarget).data("bs."+this.type,e)),t instanceof g.Event&&(e.inState["focusout"==t.type?"focus":"hover"]=!1),!e.isInStateTrue()){if(clearTimeout(e.timeout),e.hoverState="out",!e.options.delay||!e.options.delay.hide)return e.hide();e.timeout=setTimeout(function(){"out"==e.hoverState&&e.hide()},e.options.delay.hide)}},m.prototype.show=function(){var t=g.Event("show.bs."+this.type);if(this.hasContent()&&this.enabled){this.$element.trigger(t);var e=g.contains(this.$element[0].ownerDocument.documentElement,this.$element[0]);if(t.isDefaultPrevented()||!e)return;var i=this,o=this.tip(),n=this.getUID(this.type);this.setContent(),o.attr("id",n),this.$element.attr("aria-describedby",n),this.options.animation&&o.addClass("fade");var s="function"==typeof this.options.placement?this.options.placement.call(this,o[0],this.$element[0]):this.options.placement,a=/\s?auto?\s?/i,r=a.test(s);r&&(s=s.replace(a,"")||"top"),o.detach().css({top:0,left:0,display:"block"}).addClass(s).data("bs."+this.type,this),this.options.container?o.appendTo(g(document).find(this.options.container)):o.insertAfter(this.$element),this.$element.trigger("inserted.bs."+this.type);var l=this.getPosition(),h=o[0].offsetWidth,d=o[0].offsetHeight;if(r){var p=s,c=this.getPosition(this.$viewport);s="bottom"==s&&l.bottom+d>c.bottom?"top":"top"==s&&l.top-dc.width?"left":"left"==s&&l.left-ha.top+a.height&&(n.top=a.top+a.height-l)}else{var h=e.left-s,d=e.left+s+i;ha.right&&(n.left=a.left+a.width-d)}return n},m.prototype.getTitle=function(){var t=this.$element,e=this.options;return t.attr("data-original-title")||("function"==typeof e.title?e.title.call(t[0]):e.title)},m.prototype.getUID=function(t){for(;t+=~~(1e6*Math.random()),document.getElementById(t););return t},m.prototype.tip=function(){if(!this.$tip&&(this.$tip=g(this.options.template),1!=this.$tip.length))throw new Error(this.type+" `template` option must consist of exactly 1 top-level element!");return this.$tip},m.prototype.arrow=function(){return this.$arrow=this.$arrow||this.tip().find(".tooltip-arrow")},m.prototype.enable=function(){this.enabled=!0},m.prototype.disable=function(){this.enabled=!1},m.prototype.toggleEnabled=function(){this.enabled=!this.enabled},m.prototype.toggle=function(t){var e=this;t&&((e=g(t.currentTarget).data("bs."+this.type))||(e=new this.constructor(t.currentTarget,this.getDelegateOptions()),g(t.currentTarget).data("bs."+this.type,e))),t?(e.inState.click=!e.inState.click,e.isInStateTrue()?e.enter(e):e.leave(e)):e.tip().hasClass("in")?e.leave(e):e.enter(e)},m.prototype.destroy=function(){var t=this;clearTimeout(this.timeout),this.hide(function(){t.$element.off("."+t.type).removeData("bs."+t.type),t.$tip&&t.$tip.detach(),t.$tip=null,t.$arrow=null,t.$viewport=null,t.$element=null})},m.prototype.sanitizeHtml=function(t){return n(t,this.options.whiteList,this.options.sanitizeFn)};var e=g.fn.tooltip;g.fn.tooltip=function i(o){return this.each(function(){var t=g(this),e=t.data("bs.tooltip"),i="object"==typeof o&&o;!e&&/destroy|hide/.test(o)||(e||t.data("bs.tooltip",e=new m(this,i)),"string"==typeof o&&e[o]())})},g.fn.tooltip.Constructor=m,g.fn.tooltip.noConflict=function(){return g.fn.tooltip=e,this}}(jQuery),function(n){"use strict";var s=function(t,e){this.init("popover",t,e)};if(!n.fn.tooltip)throw new Error("Popover requires tooltip.js");s.VERSION="3.4.1",s.DEFAULTS=n.extend({},n.fn.tooltip.Constructor.DEFAULTS,{placement:"right",trigger:"click",content:"",template:''}),((s.prototype=n.extend({},n.fn.tooltip.Constructor.prototype)).constructor=s).prototype.getDefaults=function(){return s.DEFAULTS},s.prototype.setContent=function(){var t=this.tip(),e=this.getTitle(),i=this.getContent();if(this.options.html){var o=typeof i;this.options.sanitize&&(e=this.sanitizeHtml(e),"string"===o&&(i=this.sanitizeHtml(i))),t.find(".popover-title").html(e),t.find(".popover-content").children().detach().end()["string"===o?"html":"append"](i)}else t.find(".popover-title").text(e),t.find(".popover-content").children().detach().end().text(i);t.removeClass("fade top bottom left right in"),t.find(".popover-title").html()||t.find(".popover-title").hide()},s.prototype.hasContent=function(){return this.getTitle()||this.getContent()},s.prototype.getContent=function(){var t=this.$element,e=this.options;return t.attr("data-content")||("function"==typeof e.content?e.content.call(t[0]):e.content)},s.prototype.arrow=function(){return this.$arrow=this.$arrow||this.tip().find(".arrow")};var t=n.fn.popover;n.fn.popover=function e(o){return this.each(function(){var t=n(this),e=t.data("bs.popover"),i="object"==typeof o&&o;!e&&/destroy|hide/.test(o)||(e||t.data("bs.popover",e=new s(this,i)),"string"==typeof o&&e[o]())})},n.fn.popover.Constructor=s,n.fn.popover.noConflict=function(){return n.fn.popover=t,this}}(jQuery),function(s){"use strict";function n(t,e){this.$body=s(document.body),this.$scrollElement=s(t).is(document.body)?s(window):s(t),this.options=s.extend({},n.DEFAULTS,e),this.selector=(this.options.target||"")+" .nav li > a",this.offsets=[],this.targets=[],this.activeTarget=null,this.scrollHeight=0,this.$scrollElement.on("scroll.bs.scrollspy",s.proxy(this.process,this)),this.refresh(),this.process()}function e(o){return this.each(function(){var t=s(this),e=t.data("bs.scrollspy"),i="object"==typeof o&&o;e||t.data("bs.scrollspy",e=new n(this,i)),"string"==typeof o&&e[o]()})}n.VERSION="3.4.1",n.DEFAULTS={offset:10},n.prototype.getScrollHeight=function(){return this.$scrollElement[0].scrollHeight||Math.max(this.$body[0].scrollHeight,document.documentElement.scrollHeight)},n.prototype.refresh=function(){var t=this,o="offset",n=0;this.offsets=[],this.targets=[],this.scrollHeight=this.getScrollHeight(),s.isWindow(this.$scrollElement[0])||(o="position",n=this.$scrollElement.scrollTop()),this.$body.find(this.selector).map(function(){var t=s(this),e=t.data("target")||t.attr("href"),i=/^#./.test(e)&&s(e);return i&&i.length&&i.is(":visible")&&[[i[o]().top+n,e]]||null}).sort(function(t,e){return t[0]-e[0]}).each(function(){t.offsets.push(this[0]),t.targets.push(this[1])})},n.prototype.process=function(){var t,e=this.$scrollElement.scrollTop()+this.options.offset,i=this.getScrollHeight(),o=this.options.offset+i-this.$scrollElement.height(),n=this.offsets,s=this.targets,a=this.activeTarget;if(this.scrollHeight!=i&&this.refresh(),o<=e)return a!=(t=s[s.length-1])&&this.activate(t);if(a&&e=n[t]&&(n[t+1]===undefined||e .active"),n=i&&r.support.transition&&(o.length&&o.hasClass("fade")||!!e.find("> .fade").length);function s(){o.removeClass("active").find("> .dropdown-menu > .active").removeClass("active").end().find('[data-toggle="tab"]').attr("aria-expanded",!1),t.addClass("active").find('[data-toggle="tab"]').attr("aria-expanded",!0),n?(t[0].offsetWidth,t.addClass("in")):t.removeClass("fade"),t.parent(".dropdown-menu").length&&t.closest("li.dropdown").addClass("active").end().find('[data-toggle="tab"]').attr("aria-expanded",!0),i&&i()}o.length&&n?o.one("bsTransitionEnd",s).emulateTransitionEnd(a.TRANSITION_DURATION):s(),o.removeClass("in")};var t=r.fn.tab;r.fn.tab=e,r.fn.tab.Constructor=a,r.fn.tab.noConflict=function(){return r.fn.tab=t,this};var i=function(t){t.preventDefault(),e.call(r(this),"show")};r(document).on("click.bs.tab.data-api",'[data-toggle="tab"]',i).on("click.bs.tab.data-api",'[data-toggle="pill"]',i)}(jQuery),function(l){"use strict";var h=function(t,e){this.options=l.extend({},h.DEFAULTS,e);var i=this.options.target===h.DEFAULTS.target?l(this.options.target):l(document).find(this.options.target);this.$target=i.on("scroll.bs.affix.data-api",l.proxy(this.checkPosition,this)).on("click.bs.affix.data-api",l.proxy(this.checkPositionWithEventLoop,this)),this.$element=l(t),this.affixed=null,this.unpin=null,this.pinnedOffset=null,this.checkPosition()};function i(o){return this.each(function(){var t=l(this),e=t.data("bs.affix"),i="object"==typeof o&&o;e||t.data("bs.affix",e=new h(this,i)),"string"==typeof o&&e[o]()})}h.VERSION="3.4.1",h.RESET="affix affix-top affix-bottom",h.DEFAULTS={offset:0,target:window},h.prototype.getState=function(t,e,i,o){var n=this.$target.scrollTop(),s=this.$element.offset(),a=this.$target.height();if(null!=i&&"top"==this.affixed)return n 0 && arguments[0] !== undefined ? arguments[0] : {}; + + _classCallCheck(this, BasicAuthentication); + + var username = options.username; + var password = options.password; + var hash = window.btoa(username + ':' + password); + this.auth = 'Basic ' + hash; + } + + _createClass(BasicAuthentication, [{ + key: 'authenticate', + value: function authenticate(options) { + options.headers['Authorization'] = this.auth; + return options; + } + }]); + + return BasicAuthentication; +}(); + +module.exports = { + BasicAuthentication: BasicAuthentication +}; + +},{}],2:[function(require,module,exports){ +'use strict'; + +var basic = require('./basic'); +var session = require('./session'); +var token = require('./token'); + +module.exports = { + BasicAuthentication: basic.BasicAuthentication, + SessionAuthentication: session.SessionAuthentication, + TokenAuthentication: token.TokenAuthentication +}; + +},{"./basic":1,"./session":3,"./token":4}],3:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var utils = require('../utils'); + +function trim(str) { + return str.replace(/^\s\s*/, '').replace(/\s\s*$/, ''); +} + +function getCookie(cookieName, cookieString) { + cookieString = cookieString || window.document.cookie; + if (cookieString && cookieString !== '') { + var cookies = cookieString.split(';'); + for (var i = 0; i < cookies.length; i++) { + var cookie = trim(cookies[i]); + // Does this cookie string begin with the name we want? + if (cookie.substring(0, cookieName.length + 1) === cookieName + '=') { + return decodeURIComponent(cookie.substring(cookieName.length + 1)); + } + } + } + return null; +} + +var SessionAuthentication = function () { + function SessionAuthentication() { + var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {}; + + _classCallCheck(this, SessionAuthentication); + + this.csrfToken = getCookie(options.csrfCookieName, options.cookieString); + this.csrfHeaderName = options.csrfHeaderName; + } + + _createClass(SessionAuthentication, [{ + key: 'authenticate', + value: function authenticate(options) { + options.credentials = 'same-origin'; + if (this.csrfToken && !utils.csrfSafeMethod(options.method)) { + options.headers[this.csrfHeaderName] = this.csrfToken; + } + return options; + } + }]); + + return SessionAuthentication; +}(); + +module.exports = { + SessionAuthentication: SessionAuthentication +}; + +},{"../utils":15}],4:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var TokenAuthentication = function () { + function TokenAuthentication() { + var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {}; + + _classCallCheck(this, TokenAuthentication); + + this.token = options.token; + this.scheme = options.scheme || 'Bearer'; + } + + _createClass(TokenAuthentication, [{ + key: 'authenticate', + value: function authenticate(options) { + options.headers['Authorization'] = this.scheme + ' ' + this.token; + return options; + } + }]); + + return TokenAuthentication; +}(); + +module.exports = { + TokenAuthentication: TokenAuthentication +}; + +},{}],5:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var document = require('./document'); +var codecs = require('./codecs'); +var errors = require('./errors'); +var transports = require('./transports'); +var utils = require('./utils'); + +function lookupLink(node, keys) { + var _iteratorNormalCompletion = true; + var _didIteratorError = false; + var _iteratorError = undefined; + + try { + for (var _iterator = keys[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) { + var key = _step.value; + + if (node instanceof document.Document) { + node = node.content[key]; + } else { + node = node[key]; + } + if (node === undefined) { + throw new errors.LinkLookupError('Invalid link lookup: ' + JSON.stringify(keys)); + } + } + } catch (err) { + _didIteratorError = true; + _iteratorError = err; + } finally { + try { + if (!_iteratorNormalCompletion && _iterator.return) { + _iterator.return(); + } + } finally { + if (_didIteratorError) { + throw _iteratorError; + } + } + } + + if (!(node instanceof document.Link)) { + throw new errors.LinkLookupError('Invalid link lookup: ' + JSON.stringify(keys)); + } + return node; +} + +var Client = function () { + function Client() { + var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {}; + + _classCallCheck(this, Client); + + var transportOptions = { + auth: options.auth || null, + headers: options.headers || {}, + requestCallback: options.requestCallback, + responseCallback: options.responseCallback + }; + + this.decoders = options.decoders || [new codecs.CoreJSONCodec(), new codecs.JSONCodec(), new codecs.TextCodec()]; + this.transports = options.transports || [new transports.HTTPTransport(transportOptions)]; + } + + _createClass(Client, [{ + key: 'action', + value: function action(document, keys) { + var params = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {}; + + var link = lookupLink(document, keys); + var transport = utils.determineTransport(this.transports, link.url); + return transport.action(link, this.decoders, params); + } + }, { + key: 'get', + value: function get(url) { + var link = new document.Link(url, 'get'); + var transport = utils.determineTransport(this.transports, url); + return transport.action(link, this.decoders); + } + }]); + + return Client; +}(); + +module.exports = { + Client: Client +}; + +},{"./codecs":7,"./document":10,"./errors":11,"./transports":14,"./utils":15}],6:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +var _typeof = typeof Symbol === "function" && typeof Symbol.iterator === "symbol" ? function (obj) { return typeof obj; } : function (obj) { return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }; + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var document = require('../document'); +var URL = require('url-parse'); + +function unescapeKey(key) { + if (key.match(/__(type|meta)$/)) { + return key.substring(1); + } + return key; +} + +function getString(obj, key) { + var value = obj[key]; + if (typeof value === 'string') { + return value; + } + return ''; +} + +function getBoolean(obj, key) { + var value = obj[key]; + if (typeof value === 'boolean') { + return value; + } + return false; +} + +function getObject(obj, key) { + var value = obj[key]; + if ((typeof value === 'undefined' ? 'undefined' : _typeof(value)) === 'object') { + return value; + } + return {}; +} + +function getArray(obj, key) { + var value = obj[key]; + if (value instanceof Array) { + return value; + } + return []; +} + +function getContent(data, baseUrl) { + var excluded = ['_type', '_meta']; + var content = {}; + for (var property in data) { + if (data.hasOwnProperty(property) && !excluded.includes(property)) { + var key = unescapeKey(property); + var value = primitiveToNode(data[property], baseUrl); + content[key] = value; + } + } + return content; +} + +function primitiveToNode(data, baseUrl) { + var isObject = data instanceof Object && !(data instanceof Array); + + if (isObject && data._type === 'document') { + // Document + var meta = getObject(data, '_meta'); + var relativeUrl = getString(meta, 'url'); + var url = relativeUrl ? URL(relativeUrl, baseUrl).toString() : ''; + var title = getString(meta, 'title'); + var description = getString(meta, 'description'); + var content = getContent(data, url); + return new document.Document(url, title, description, content); + } else if (isObject && data._type === 'link') { + // Link + var _relativeUrl = getString(data, 'url'); + var _url = _relativeUrl ? URL(_relativeUrl, baseUrl).toString() : ''; + var method = getString(data, 'action') || 'get'; + var _title = getString(data, 'title'); + var _description = getString(data, 'description'); + var fieldsData = getArray(data, 'fields'); + var fields = []; + for (var idx = 0, len = fieldsData.length; idx < len; idx++) { + var value = fieldsData[idx]; + var name = getString(value, 'name'); + var required = getBoolean(value, 'required'); + var location = getString(value, 'location'); + var fieldDescription = getString(value, 'fieldDescription'); + var field = new document.Field(name, required, location, fieldDescription); + fields.push(field); + } + return new document.Link(_url, method, 'application/json', fields, _title, _description); + } else if (isObject) { + // Object + var _content = {}; + for (var key in data) { + if (data.hasOwnProperty(key)) { + _content[key] = primitiveToNode(data[key], baseUrl); + } + } + return _content; + } else if (data instanceof Array) { + // Object + var _content2 = []; + for (var _idx = 0, _len = data.length; _idx < _len; _idx++) { + _content2.push(primitiveToNode(data[_idx], baseUrl)); + } + return _content2; + } + // Primitive + return data; +} + +var CoreJSONCodec = function () { + function CoreJSONCodec() { + _classCallCheck(this, CoreJSONCodec); + + this.mediaType = 'application/coreapi+json'; + } + + _createClass(CoreJSONCodec, [{ + key: 'decode', + value: function decode(text) { + var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {}; + + var data = text; + if (options.preloaded === undefined || !options.preloaded) { + data = JSON.parse(text); + } + return primitiveToNode(data, options.url); + } + }]); + + return CoreJSONCodec; +}(); + +module.exports = { + CoreJSONCodec: CoreJSONCodec +}; + +},{"../document":10,"url-parse":19}],7:[function(require,module,exports){ +'use strict'; + +var corejson = require('./corejson'); +var json = require('./json'); +var text = require('./text'); + +module.exports = { + CoreJSONCodec: corejson.CoreJSONCodec, + JSONCodec: json.JSONCodec, + TextCodec: text.TextCodec +}; + +},{"./corejson":6,"./json":8,"./text":9}],8:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var JSONCodec = function () { + function JSONCodec() { + _classCallCheck(this, JSONCodec); + + this.mediaType = 'application/json'; + } + + _createClass(JSONCodec, [{ + key: 'decode', + value: function decode(text) { + var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {}; + + return JSON.parse(text); + } + }]); + + return JSONCodec; +}(); + +module.exports = { + JSONCodec: JSONCodec +}; + +},{}],9:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var TextCodec = function () { + function TextCodec() { + _classCallCheck(this, TextCodec); + + this.mediaType = 'text/*'; + } + + _createClass(TextCodec, [{ + key: 'decode', + value: function decode(text) { + var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {}; + + return text; + } + }]); + + return TextCodec; +}(); + +module.exports = { + TextCodec: TextCodec +}; + +},{}],10:[function(require,module,exports){ +'use strict'; + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var Document = function Document() { + var url = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ''; + var title = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : ''; + var description = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : ''; + var content = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {}; + + _classCallCheck(this, Document); + + this.url = url; + this.title = title; + this.description = description; + this.content = content; +}; + +var Link = function Link(url, method) { + var encoding = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'application/json'; + var fields = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : []; + var title = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : ''; + var description = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : ''; + + _classCallCheck(this, Link); + + if (url === undefined) { + throw new Error('url argument is required'); + } + + if (method === undefined) { + throw new Error('method argument is required'); + } + + this.url = url; + this.method = method; + this.encoding = encoding; + this.fields = fields; + this.title = title; + this.description = description; +}; + +var Field = function Field(name) { + var required = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false; + var location = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : ''; + var description = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : ''; + + _classCallCheck(this, Field); + + if (name === undefined) { + throw new Error('name argument is required'); + } + + this.name = name; + this.required = required; + this.location = location; + this.description = description; +}; + +module.exports = { + Document: Document, + Link: Link, + Field: Field +}; + +},{}],11:[function(require,module,exports){ +'use strict'; + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +function _possibleConstructorReturn(self, call) { if (!self) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return call && (typeof call === "object" || typeof call === "function") ? call : self; } + +function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function, not " + typeof superClass); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, enumerable: false, writable: true, configurable: true } }); if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass; } + +var ParameterError = function (_Error) { + _inherits(ParameterError, _Error); + + function ParameterError(message) { + _classCallCheck(this, ParameterError); + + var _this = _possibleConstructorReturn(this, (ParameterError.__proto__ || Object.getPrototypeOf(ParameterError)).call(this, message)); + + _this.message = message; + _this.name = 'ParameterError'; + return _this; + } + + return ParameterError; +}(Error); + +var LinkLookupError = function (_Error2) { + _inherits(LinkLookupError, _Error2); + + function LinkLookupError(message) { + _classCallCheck(this, LinkLookupError); + + var _this2 = _possibleConstructorReturn(this, (LinkLookupError.__proto__ || Object.getPrototypeOf(LinkLookupError)).call(this, message)); + + _this2.message = message; + _this2.name = 'LinkLookupError'; + return _this2; + } + + return LinkLookupError; +}(Error); + +var ErrorMessage = function (_Error3) { + _inherits(ErrorMessage, _Error3); + + function ErrorMessage(message, content) { + _classCallCheck(this, ErrorMessage); + + var _this3 = _possibleConstructorReturn(this, (ErrorMessage.__proto__ || Object.getPrototypeOf(ErrorMessage)).call(this, message)); + + _this3.message = message; + _this3.content = content; + _this3.name = 'ErrorMessage'; + return _this3; + } + + return ErrorMessage; +}(Error); + +module.exports = { + ParameterError: ParameterError, + LinkLookupError: LinkLookupError, + ErrorMessage: ErrorMessage +}; + +},{}],12:[function(require,module,exports){ +'use strict'; + +var auth = require('./auth'); +var client = require('./client'); +var codecs = require('./codecs'); +var document = require('./document'); +var errors = require('./errors'); +var transports = require('./transports'); +var utils = require('./utils'); + +var coreapi = { + Client: client.Client, + Document: document.Document, + Link: document.Link, + auth: auth, + codecs: codecs, + errors: errors, + transports: transports, + utils: utils +}; + +module.exports = coreapi; + +},{"./auth":2,"./client":5,"./codecs":7,"./document":10,"./errors":11,"./transports":14,"./utils":15}],13:[function(require,module,exports){ +'use strict'; + +var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }(); + +function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } } + +var fetch = require('isomorphic-fetch'); +var errors = require('../errors'); +var utils = require('../utils'); +var URL = require('url-parse'); +var urlTemplate = require('url-template'); + +var parseResponse = function parseResponse(response, decoders, responseCallback) { + return response.text().then(function (text) { + if (responseCallback) { + responseCallback(response, text); + } + var contentType = response.headers.get('Content-Type'); + var decoder = utils.negotiateDecoder(decoders, contentType); + var options = { url: response.url }; + return decoder.decode(text, options); + }); +}; + +var HTTPTransport = function () { + function HTTPTransport() { + var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {}; + + _classCallCheck(this, HTTPTransport); + + this.schemes = ['http', 'https']; + this.auth = options.auth || null; + this.headers = options.headers || {}; + this.fetch = options.fetch || fetch; + this.FormData = options.FormData || window.FormData; + this.requestCallback = options.requestCallback; + this.responseCallback = options.responseCallback; + } + + _createClass(HTTPTransport, [{ + key: 'buildRequest', + value: function buildRequest(link, decoders) { + var params = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {}; + + var fields = link.fields; + var method = link.method.toUpperCase(); + var queryParams = {}; + var pathParams = {}; + var formParams = {}; + var fieldNames = []; + var hasBody = false; + + for (var idx = 0, len = fields.length; idx < len; idx++) { + var field = fields[idx]; + + // Ensure any required fields are included + if (!params.hasOwnProperty(field.name)) { + if (field.required) { + throw new errors.ParameterError('Missing required field: "' + field.name + '"'); + } else { + continue; + } + } + + fieldNames.push(field.name); + if (field.location === 'query') { + queryParams[field.name] = params[field.name]; + } else if (field.location === 'path') { + pathParams[field.name] = params[field.name]; + } else if (field.location === 'form') { + formParams[field.name] = params[field.name]; + hasBody = true; + } else if (field.location === 'body') { + formParams = params[field.name]; + hasBody = true; + } + } + + // Check for any parameters that did not have a matching field + for (var property in params) { + if (params.hasOwnProperty(property) && !fieldNames.includes(property)) { + throw new errors.ParameterError('Unknown parameter: "' + property + '"'); + } + } + + var requestOptions = { method: method, headers: {} }; + + Object.assign(requestOptions.headers, this.headers); + + if (hasBody) { + if (link.encoding === 'application/json') { + requestOptions.body = JSON.stringify(formParams); + requestOptions.headers['Content-Type'] = 'application/json'; + } else if (link.encoding === 'multipart/form-data') { + var form = new this.FormData(); + + for (var paramKey in formParams) { + form.append(paramKey, formParams[paramKey]); + } + requestOptions.body = form; + } else if (link.encoding === 'application/x-www-form-urlencoded') { + var formBody = []; + for (var _paramKey in formParams) { + var encodedKey = encodeURIComponent(_paramKey); + var encodedValue = encodeURIComponent(formParams[_paramKey]); + formBody.push(encodedKey + '=' + encodedValue); + } + formBody = formBody.join('&'); + + requestOptions.body = formBody; + requestOptions.headers['Content-Type'] = 'application/x-www-form-urlencoded'; + } + } + + if (this.auth) { + requestOptions = this.auth.authenticate(requestOptions); + } + + var parsedUrl = urlTemplate.parse(link.url); + parsedUrl = parsedUrl.expand(pathParams); + parsedUrl = new URL(parsedUrl); + parsedUrl.set('query', queryParams); + + return { + url: parsedUrl.toString(), + options: requestOptions + }; + } + }, { + key: 'action', + value: function action(link, decoders) { + var params = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {}; + + var responseCallback = this.responseCallback; + var request = this.buildRequest(link, decoders, params); + + if (this.requestCallback) { + this.requestCallback(request); + } + + return this.fetch(request.url, request.options).then(function (response) { + if (response.status === 204) { + return; + } + return parseResponse(response, decoders, responseCallback).then(function (data) { + if (response.ok) { + return data; + } else { + var title = response.status + ' ' + response.statusText; + var error = new errors.ErrorMessage(title, data); + return Promise.reject(error); + } + }); + }); + } + }]); + + return HTTPTransport; +}(); + +module.exports = { + HTTPTransport: HTTPTransport +}; + +},{"../errors":11,"../utils":15,"isomorphic-fetch":16,"url-parse":19,"url-template":21}],14:[function(require,module,exports){ +'use strict'; + +var http = require('./http'); + +module.exports = { + HTTPTransport: http.HTTPTransport +}; + +},{"./http":13}],15:[function(require,module,exports){ +'use strict'; + +var URL = require('url-parse'); + +var determineTransport = function determineTransport(transports, url) { + var parsedUrl = new URL(url); + var scheme = parsedUrl.protocol.replace(':', ''); + + var _iteratorNormalCompletion = true; + var _didIteratorError = false; + var _iteratorError = undefined; + + try { + for (var _iterator = transports[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) { + var transport = _step.value; + + if (transport.schemes.includes(scheme)) { + return transport; + } + } + } catch (err) { + _didIteratorError = true; + _iteratorError = err; + } finally { + try { + if (!_iteratorNormalCompletion && _iterator.return) { + _iterator.return(); + } + } finally { + if (_didIteratorError) { + throw _iteratorError; + } + } + } + + throw Error('Unsupported scheme in URL: ' + url); +}; + +var negotiateDecoder = function negotiateDecoder(decoders, contentType) { + if (contentType === undefined || contentType === null) { + return decoders[0]; + } + + var fullType = contentType.toLowerCase().split(';')[0].trim(); + var mainType = fullType.split('/')[0] + '/*'; + var wildcardType = '*/*'; + var acceptableTypes = [fullType, mainType, wildcardType]; + + var _iteratorNormalCompletion2 = true; + var _didIteratorError2 = false; + var _iteratorError2 = undefined; + + try { + for (var _iterator2 = decoders[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true) { + var decoder = _step2.value; + + if (acceptableTypes.includes(decoder.mediaType)) { + return decoder; + } + } + } catch (err) { + _didIteratorError2 = true; + _iteratorError2 = err; + } finally { + try { + if (!_iteratorNormalCompletion2 && _iterator2.return) { + _iterator2.return(); + } + } finally { + if (_didIteratorError2) { + throw _iteratorError2; + } + } + } + + throw Error('Unsupported media in Content-Type header: ' + contentType); +}; + +var csrfSafeMethod = function csrfSafeMethod(method) { + // these HTTP methods do not require CSRF protection + return (/^(GET|HEAD|OPTIONS|TRACE)$/.test(method) + ); +}; + +module.exports = { + determineTransport: determineTransport, + negotiateDecoder: negotiateDecoder, + csrfSafeMethod: csrfSafeMethod +}; + +},{"url-parse":19}],16:[function(require,module,exports){ +// the whatwg-fetch polyfill installs the fetch() function +// on the global object (window or self) +// +// Return that as the export for use in Webpack, Browserify etc. +require('whatwg-fetch'); +module.exports = self.fetch.bind(self); + +},{"whatwg-fetch":22}],17:[function(require,module,exports){ +'use strict'; + +var has = Object.prototype.hasOwnProperty; + +/** + * Simple query string parser. + * + * @param {String} query The query string that needs to be parsed. + * @returns {Object} + * @api public + */ +function querystring(query) { + var parser = /([^=?&]+)=?([^&]*)/g + , result = {} + , part; + + // + // Little nifty parsing hack, leverage the fact that RegExp.exec increments + // the lastIndex property so we can continue executing this loop until we've + // parsed all results. + // + for (; + part = parser.exec(query); + result[decodeURIComponent(part[1])] = decodeURIComponent(part[2]) + ); + + return result; +} + +/** + * Transform a query string to an object. + * + * @param {Object} obj Object that should be transformed. + * @param {String} prefix Optional prefix. + * @returns {String} + * @api public + */ +function querystringify(obj, prefix) { + prefix = prefix || ''; + + var pairs = []; + + // + // Optionally prefix with a '?' if needed + // + if ('string' !== typeof prefix) prefix = '?'; + + for (var key in obj) { + if (has.call(obj, key)) { + pairs.push(encodeURIComponent(key) +'='+ encodeURIComponent(obj[key])); + } + } + + return pairs.length ? prefix + pairs.join('&') : ''; +} + +// +// Expose the module. +// +exports.stringify = querystringify; +exports.parse = querystring; + +},{}],18:[function(require,module,exports){ +'use strict'; + +/** + * Check if we're required to add a port number. + * + * @see https://url.spec.whatwg.org/#default-port + * @param {Number|String} port Port number we need to check + * @param {String} protocol Protocol we need to check against. + * @returns {Boolean} Is it a default port for the given protocol + * @api private + */ +module.exports = function required(port, protocol) { + protocol = protocol.split(':')[0]; + port = +port; + + if (!port) return false; + + switch (protocol) { + case 'http': + case 'ws': + return port !== 80; + + case 'https': + case 'wss': + return port !== 443; + + case 'ftp': + return port !== 21; + + case 'gopher': + return port !== 70; + + case 'file': + return false; + } + + return port !== 0; +}; + +},{}],19:[function(require,module,exports){ +'use strict'; + +var required = require('requires-port') + , lolcation = require('./lolcation') + , qs = require('querystringify') + , protocolre = /^([a-z][a-z0-9.+-]*:)?(\/\/)?([\S\s]*)/i; + +/** + * These are the parse rules for the URL parser, it informs the parser + * about: + * + * 0. The char it Needs to parse, if it's a string it should be done using + * indexOf, RegExp using exec and NaN means set as current value. + * 1. The property we should set when parsing this value. + * 2. Indication if it's backwards or forward parsing, when set as number it's + * the value of extra chars that should be split off. + * 3. Inherit from location if non existing in the parser. + * 4. `toLowerCase` the resulting value. + */ +var rules = [ + ['#', 'hash'], // Extract from the back. + ['?', 'query'], // Extract from the back. + ['/', 'pathname'], // Extract from the back. + ['@', 'auth', 1], // Extract from the front. + [NaN, 'host', undefined, 1, 1], // Set left over value. + [/:(\d+)$/, 'port', undefined, 1], // RegExp the back. + [NaN, 'hostname', undefined, 1, 1] // Set left over. +]; + +/** + * @typedef ProtocolExtract + * @type Object + * @property {String} protocol Protocol matched in the URL, in lowercase. + * @property {Boolean} slashes `true` if protocol is followed by "//", else `false`. + * @property {String} rest Rest of the URL that is not part of the protocol. + */ + +/** + * Extract protocol information from a URL with/without double slash ("//"). + * + * @param {String} address URL we want to extract from. + * @return {ProtocolExtract} Extracted information. + * @api private + */ +function extractProtocol(address) { + var match = protocolre.exec(address); + + return { + protocol: match[1] ? match[1].toLowerCase() : '', + slashes: !!match[2], + rest: match[3] + }; +} + +/** + * Resolve a relative URL pathname against a base URL pathname. + * + * @param {String} relative Pathname of the relative URL. + * @param {String} base Pathname of the base URL. + * @return {String} Resolved pathname. + * @api private + */ +function resolve(relative, base) { + var path = (base || '/').split('/').slice(0, -1).concat(relative.split('/')) + , i = path.length + , last = path[i - 1] + , unshift = false + , up = 0; + + while (i--) { + if (path[i] === '.') { + path.splice(i, 1); + } else if (path[i] === '..') { + path.splice(i, 1); + up++; + } else if (up) { + if (i === 0) unshift = true; + path.splice(i, 1); + up--; + } + } + + if (unshift) path.unshift(''); + if (last === '.' || last === '..') path.push(''); + + return path.join('/'); +} + +/** + * The actual URL instance. Instead of returning an object we've opted-in to + * create an actual constructor as it's much more memory efficient and + * faster and it pleases my OCD. + * + * @constructor + * @param {String} address URL we want to parse. + * @param {Object|String} location Location defaults for relative paths. + * @param {Boolean|Function} parser Parser for the query string. + * @api public + */ +function URL(address, location, parser) { + if (!(this instanceof URL)) { + return new URL(address, location, parser); + } + + var relative, extracted, parse, instruction, index, key + , instructions = rules.slice() + , type = typeof location + , url = this + , i = 0; + + // + // The following if statements allows this module two have compatibility with + // 2 different API: + // + // 1. Node.js's `url.parse` api which accepts a URL, boolean as arguments + // where the boolean indicates that the query string should also be parsed. + // + // 2. The `URL` interface of the browser which accepts a URL, object as + // arguments. The supplied object will be used as default values / fall-back + // for relative paths. + // + if ('object' !== type && 'string' !== type) { + parser = location; + location = null; + } + + if (parser && 'function' !== typeof parser) parser = qs.parse; + + location = lolcation(location); + + // + // Extract protocol information before running the instructions. + // + extracted = extractProtocol(address || ''); + relative = !extracted.protocol && !extracted.slashes; + url.slashes = extracted.slashes || relative && location.slashes; + url.protocol = extracted.protocol || location.protocol || ''; + address = extracted.rest; + + // + // When the authority component is absent the URL starts with a path + // component. + // + if (!extracted.slashes) instructions[2] = [/(.*)/, 'pathname']; + + for (; i < instructions.length; i++) { + instruction = instructions[i]; + parse = instruction[0]; + key = instruction[1]; + + if (parse !== parse) { + url[key] = address; + } else if ('string' === typeof parse) { + if (~(index = address.indexOf(parse))) { + if ('number' === typeof instruction[2]) { + url[key] = address.slice(0, index); + address = address.slice(index + instruction[2]); + } else { + url[key] = address.slice(index); + address = address.slice(0, index); + } + } + } else if (index = parse.exec(address)) { + url[key] = index[1]; + address = address.slice(0, index.index); + } + + url[key] = url[key] || ( + relative && instruction[3] ? location[key] || '' : '' + ); + + // + // Hostname, host and protocol should be lowercased so they can be used to + // create a proper `origin`. + // + if (instruction[4]) url[key] = url[key].toLowerCase(); + } + + // + // Also parse the supplied query string in to an object. If we're supplied + // with a custom parser as function use that instead of the default build-in + // parser. + // + if (parser) url.query = parser(url.query); + + // + // If the URL is relative, resolve the pathname against the base URL. + // + if ( + relative + && location.slashes + && url.pathname.charAt(0) !== '/' + && (url.pathname !== '' || location.pathname !== '') + ) { + url.pathname = resolve(url.pathname, location.pathname); + } + + // + // We should not add port numbers if they are already the default port number + // for a given protocol. As the host also contains the port number we're going + // override it with the hostname which contains no port number. + // + if (!required(url.port, url.protocol)) { + url.host = url.hostname; + url.port = ''; + } + + // + // Parse down the `auth` for the username and password. + // + url.username = url.password = ''; + if (url.auth) { + instruction = url.auth.split(':'); + url.username = instruction[0] || ''; + url.password = instruction[1] || ''; + } + + url.origin = url.protocol && url.host && url.protocol !== 'file:' + ? url.protocol +'//'+ url.host + : 'null'; + + // + // The href is just the compiled result. + // + url.href = url.toString(); +} + +/** + * This is convenience method for changing properties in the URL instance to + * insure that they all propagate correctly. + * + * @param {String} part Property we need to adjust. + * @param {Mixed} value The newly assigned value. + * @param {Boolean|Function} fn When setting the query, it will be the function + * used to parse the query. + * When setting the protocol, double slash will be + * removed from the final url if it is true. + * @returns {URL} + * @api public + */ +URL.prototype.set = function set(part, value, fn) { + var url = this; + + switch (part) { + case 'query': + if ('string' === typeof value && value.length) { + value = (fn || qs.parse)(value); + } + + url[part] = value; + break; + + case 'port': + url[part] = value; + + if (!required(value, url.protocol)) { + url.host = url.hostname; + url[part] = ''; + } else if (value) { + url.host = url.hostname +':'+ value; + } + + break; + + case 'hostname': + url[part] = value; + + if (url.port) value += ':'+ url.port; + url.host = value; + break; + + case 'host': + url[part] = value; + + if (/:\d+$/.test(value)) { + value = value.split(':'); + url.port = value.pop(); + url.hostname = value.join(':'); + } else { + url.hostname = value; + url.port = ''; + } + + break; + + case 'protocol': + url.protocol = value.toLowerCase(); + url.slashes = !fn; + break; + + case 'pathname': + url.pathname = value.length && value.charAt(0) !== '/' ? '/' + value : value; + + break; + + default: + url[part] = value; + } + + for (var i = 0; i < rules.length; i++) { + var ins = rules[i]; + + if (ins[4]) url[ins[1]] = url[ins[1]].toLowerCase(); + } + + url.origin = url.protocol && url.host && url.protocol !== 'file:' + ? url.protocol +'//'+ url.host + : 'null'; + + url.href = url.toString(); + + return url; +}; + +/** + * Transform the properties back in to a valid and full URL string. + * + * @param {Function} stringify Optional query stringify function. + * @returns {String} + * @api public + */ +URL.prototype.toString = function toString(stringify) { + if (!stringify || 'function' !== typeof stringify) stringify = qs.stringify; + + var query + , url = this + , protocol = url.protocol; + + if (protocol && protocol.charAt(protocol.length - 1) !== ':') protocol += ':'; + + var result = protocol + (url.slashes ? '//' : ''); + + if (url.username) { + result += url.username; + if (url.password) result += ':'+ url.password; + result += '@'; + } + + result += url.host + url.pathname; + + query = 'object' === typeof url.query ? stringify(url.query) : url.query; + if (query) result += '?' !== query.charAt(0) ? '?'+ query : query; + + if (url.hash) result += url.hash; + + return result; +}; + +// +// Expose the URL parser and some additional properties that might be useful for +// others or testing. +// +URL.extractProtocol = extractProtocol; +URL.location = lolcation; +URL.qs = qs; + +module.exports = URL; + +},{"./lolcation":20,"querystringify":17,"requires-port":18}],20:[function(require,module,exports){ +(function (global){ +'use strict'; + +var slashes = /^[A-Za-z][A-Za-z0-9+-.]*:\/\//; + +/** + * These properties should not be copied or inherited from. This is only needed + * for all non blob URL's as a blob URL does not include a hash, only the + * origin. + * + * @type {Object} + * @private + */ +var ignore = { hash: 1, query: 1 } + , URL; + +/** + * The location object differs when your code is loaded through a normal page, + * Worker or through a worker using a blob. And with the blobble begins the + * trouble as the location object will contain the URL of the blob, not the + * location of the page where our code is loaded in. The actual origin is + * encoded in the `pathname` so we can thankfully generate a good "default" + * location from it so we can generate proper relative URL's again. + * + * @param {Object|String} loc Optional default location object. + * @returns {Object} lolcation object. + * @api public + */ +module.exports = function lolcation(loc) { + loc = loc || global.location || {}; + URL = URL || require('./'); + + var finaldestination = {} + , type = typeof loc + , key; + + if ('blob:' === loc.protocol) { + finaldestination = new URL(unescape(loc.pathname), {}); + } else if ('string' === type) { + finaldestination = new URL(loc, {}); + for (key in ignore) delete finaldestination[key]; + } else if ('object' === type) { + for (key in loc) { + if (key in ignore) continue; + finaldestination[key] = loc[key]; + } + + if (finaldestination.slashes === undefined) { + finaldestination.slashes = slashes.test(loc.href); + } + } + + return finaldestination; +}; + +}).call(this,typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : typeof window !== "undefined" ? window : {}) + +},{"./":19}],21:[function(require,module,exports){ +(function (root, factory) { + if (typeof exports === 'object') { + module.exports = factory(); + } else if (typeof define === 'function' && define.amd) { + define([], factory); + } else { + root.urltemplate = factory(); + } +}(this, function () { + /** + * @constructor + */ + function UrlTemplate() { + } + + /** + * @private + * @param {string} str + * @return {string} + */ + UrlTemplate.prototype.encodeReserved = function (str) { + return str.split(/(%[0-9A-Fa-f]{2})/g).map(function (part) { + if (!/%[0-9A-Fa-f]/.test(part)) { + part = encodeURI(part).replace(/%5B/g, '[').replace(/%5D/g, ']'); + } + return part; + }).join(''); + }; + + /** + * @private + * @param {string} str + * @return {string} + */ + UrlTemplate.prototype.encodeUnreserved = function (str) { + return encodeURIComponent(str).replace(/[!'()*]/g, function (c) { + return '%' + c.charCodeAt(0).toString(16).toUpperCase(); + }); + } + + /** + * @private + * @param {string} operator + * @param {string} value + * @param {string} key + * @return {string} + */ + UrlTemplate.prototype.encodeValue = function (operator, value, key) { + value = (operator === '+' || operator === '#') ? this.encodeReserved(value) : this.encodeUnreserved(value); + + if (key) { + return this.encodeUnreserved(key) + '=' + value; + } else { + return value; + } + }; + + /** + * @private + * @param {*} value + * @return {boolean} + */ + UrlTemplate.prototype.isDefined = function (value) { + return value !== undefined && value !== null; + }; + + /** + * @private + * @param {string} + * @return {boolean} + */ + UrlTemplate.prototype.isKeyOperator = function (operator) { + return operator === ';' || operator === '&' || operator === '?'; + }; + + /** + * @private + * @param {Object} context + * @param {string} operator + * @param {string} key + * @param {string} modifier + */ + UrlTemplate.prototype.getValues = function (context, operator, key, modifier) { + var value = context[key], + result = []; + + if (this.isDefined(value) && value !== '') { + if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') { + value = value.toString(); + + if (modifier && modifier !== '*') { + value = value.substring(0, parseInt(modifier, 10)); + } + + result.push(this.encodeValue(operator, value, this.isKeyOperator(operator) ? key : null)); + } else { + if (modifier === '*') { + if (Array.isArray(value)) { + value.filter(this.isDefined).forEach(function (value) { + result.push(this.encodeValue(operator, value, this.isKeyOperator(operator) ? key : null)); + }, this); + } else { + Object.keys(value).forEach(function (k) { + if (this.isDefined(value[k])) { + result.push(this.encodeValue(operator, value[k], k)); + } + }, this); + } + } else { + var tmp = []; + + if (Array.isArray(value)) { + value.filter(this.isDefined).forEach(function (value) { + tmp.push(this.encodeValue(operator, value)); + }, this); + } else { + Object.keys(value).forEach(function (k) { + if (this.isDefined(value[k])) { + tmp.push(this.encodeUnreserved(k)); + tmp.push(this.encodeValue(operator, value[k].toString())); + } + }, this); + } + + if (this.isKeyOperator(operator)) { + result.push(this.encodeUnreserved(key) + '=' + tmp.join(',')); + } else if (tmp.length !== 0) { + result.push(tmp.join(',')); + } + } + } + } else { + if (operator === ';') { + if (this.isDefined(value)) { + result.push(this.encodeUnreserved(key)); + } + } else if (value === '' && (operator === '&' || operator === '?')) { + result.push(this.encodeUnreserved(key) + '='); + } else if (value === '') { + result.push(''); + } + } + return result; + }; + + /** + * @param {string} template + * @return {function(Object):string} + */ + UrlTemplate.prototype.parse = function (template) { + var that = this; + var operators = ['+', '#', '.', '/', ';', '?', '&']; + + return { + expand: function (context) { + return template.replace(/\{([^\{\}]+)\}|([^\{\}]+)/g, function (_, expression, literal) { + if (expression) { + var operator = null, + values = []; + + if (operators.indexOf(expression.charAt(0)) !== -1) { + operator = expression.charAt(0); + expression = expression.substr(1); + } + + expression.split(/,/g).forEach(function (variable) { + var tmp = /([^:\*]*)(?::(\d+)|(\*))?/.exec(variable); + values.push.apply(values, that.getValues(context, operator, tmp[1], tmp[2] || tmp[3])); + }); + + if (operator && operator !== '+') { + var separator = ','; + + if (operator === '?') { + separator = '&'; + } else if (operator !== '#') { + separator = operator; + } + return (values.length !== 0 ? operator : '') + values.join(separator); + } else { + return values.join(','); + } + } else { + return that.encodeReserved(literal); + } + }); + } + }; + }; + + return new UrlTemplate(); +})); + +},{}],22:[function(require,module,exports){ +(function(self) { + 'use strict'; + + if (self.fetch) { + return + } + + var support = { + searchParams: 'URLSearchParams' in self, + iterable: 'Symbol' in self && 'iterator' in Symbol, + blob: 'FileReader' in self && 'Blob' in self && (function() { + try { + new Blob() + return true + } catch(e) { + return false + } + })(), + formData: 'FormData' in self, + arrayBuffer: 'ArrayBuffer' in self + } + + if (support.arrayBuffer) { + var viewClasses = [ + '[object Int8Array]', + '[object Uint8Array]', + '[object Uint8ClampedArray]', + '[object Int16Array]', + '[object Uint16Array]', + '[object Int32Array]', + '[object Uint32Array]', + '[object Float32Array]', + '[object Float64Array]' + ] + + var isDataView = function(obj) { + return obj && DataView.prototype.isPrototypeOf(obj) + } + + var isArrayBufferView = ArrayBuffer.isView || function(obj) { + return obj && viewClasses.indexOf(Object.prototype.toString.call(obj)) > -1 + } + } + + function normalizeName(name) { + if (typeof name !== 'string') { + name = String(name) + } + if (/[^a-z0-9\-#$%&'*+.\^_`|~]/i.test(name)) { + throw new TypeError('Invalid character in header field name') + } + return name.toLowerCase() + } + + function normalizeValue(value) { + if (typeof value !== 'string') { + value = String(value) + } + return value + } + + // Build a destructive iterator for the value list + function iteratorFor(items) { + var iterator = { + next: function() { + var value = items.shift() + return {done: value === undefined, value: value} + } + } + + if (support.iterable) { + iterator[Symbol.iterator] = function() { + return iterator + } + } + + return iterator + } + + function Headers(headers) { + this.map = {} + + if (headers instanceof Headers) { + headers.forEach(function(value, name) { + this.append(name, value) + }, this) + + } else if (headers) { + Object.getOwnPropertyNames(headers).forEach(function(name) { + this.append(name, headers[name]) + }, this) + } + } + + Headers.prototype.append = function(name, value) { + name = normalizeName(name) + value = normalizeValue(value) + var oldValue = this.map[name] + this.map[name] = oldValue ? oldValue+','+value : value + } + + Headers.prototype['delete'] = function(name) { + delete this.map[normalizeName(name)] + } + + Headers.prototype.get = function(name) { + name = normalizeName(name) + return this.has(name) ? this.map[name] : null + } + + Headers.prototype.has = function(name) { + return this.map.hasOwnProperty(normalizeName(name)) + } + + Headers.prototype.set = function(name, value) { + this.map[normalizeName(name)] = normalizeValue(value) + } + + Headers.prototype.forEach = function(callback, thisArg) { + for (var name in this.map) { + if (this.map.hasOwnProperty(name)) { + callback.call(thisArg, this.map[name], name, this) + } + } + } + + Headers.prototype.keys = function() { + var items = [] + this.forEach(function(value, name) { items.push(name) }) + return iteratorFor(items) + } + + Headers.prototype.values = function() { + var items = [] + this.forEach(function(value) { items.push(value) }) + return iteratorFor(items) + } + + Headers.prototype.entries = function() { + var items = [] + this.forEach(function(value, name) { items.push([name, value]) }) + return iteratorFor(items) + } + + if (support.iterable) { + Headers.prototype[Symbol.iterator] = Headers.prototype.entries + } + + function consumed(body) { + if (body.bodyUsed) { + return Promise.reject(new TypeError('Already read')) + } + body.bodyUsed = true + } + + function fileReaderReady(reader) { + return new Promise(function(resolve, reject) { + reader.onload = function() { + resolve(reader.result) + } + reader.onerror = function() { + reject(reader.error) + } + }) + } + + function readBlobAsArrayBuffer(blob) { + var reader = new FileReader() + var promise = fileReaderReady(reader) + reader.readAsArrayBuffer(blob) + return promise + } + + function readBlobAsText(blob) { + var reader = new FileReader() + var promise = fileReaderReady(reader) + reader.readAsText(blob) + return promise + } + + function bufferClone(buf) { + if (buf.slice) { + return buf.slice(0) + } else { + var view = new Uint8Array(buf.byteLength) + view.set(new Uint8Array(buf)) + return view.buffer + } + } + + function Body() { + this.bodyUsed = false + + this._initBody = function(body) { + this._bodyInit = body + if (!body) { + this._bodyText = '' + } else if (typeof body === 'string') { + this._bodyText = body + } else if (support.blob && Blob.prototype.isPrototypeOf(body)) { + this._bodyBlob = body + } else if (support.formData && FormData.prototype.isPrototypeOf(body)) { + this._bodyFormData = body + } else if (support.searchParams && URLSearchParams.prototype.isPrototypeOf(body)) { + this._bodyText = body.toString() + } else if (support.arrayBuffer && support.blob && isDataView(body)) { + this._bodyArrayBuffer = bufferClone(body.buffer) + // IE 10-11 can't handle a DataView body. + this._bodyInit = new Blob([this._bodyArrayBuffer]) + } else if (support.arrayBuffer && (ArrayBuffer.prototype.isPrototypeOf(body) || isArrayBufferView(body))) { + this._bodyArrayBuffer = bufferClone(body) + } else { + throw new Error('unsupported BodyInit type') + } + + if (!this.headers.get('content-type')) { + if (typeof body === 'string') { + this.headers.set('content-type', 'text/plain;charset=UTF-8') + } else if (this._bodyBlob && this._bodyBlob.type) { + this.headers.set('content-type', this._bodyBlob.type) + } else if (support.searchParams && URLSearchParams.prototype.isPrototypeOf(body)) { + this.headers.set('content-type', 'application/x-www-form-urlencoded;charset=UTF-8') + } + } + } + + if (support.blob) { + this.blob = function() { + var rejected = consumed(this) + if (rejected) { + return rejected + } + + if (this._bodyBlob) { + return Promise.resolve(this._bodyBlob) + } else if (this._bodyArrayBuffer) { + return Promise.resolve(new Blob([this._bodyArrayBuffer])) + } else if (this._bodyFormData) { + throw new Error('could not read FormData body as blob') + } else { + return Promise.resolve(new Blob([this._bodyText])) + } + } + } + + this.text = function() { + var rejected = consumed(this) + if (rejected) { + return rejected + } + + if (this._bodyBlob) { + return readBlobAsText(this._bodyBlob) + } else if (this._bodyArrayBuffer) { + var view = new Uint8Array(this._bodyArrayBuffer) + var str = String.fromCharCode.apply(null, view) + return Promise.resolve(str) + } else if (this._bodyFormData) { + throw new Error('could not read FormData body as text') + } else { + return Promise.resolve(this._bodyText) + } + } + + if (support.arrayBuffer) { + this.arrayBuffer = function() { + if (this._bodyArrayBuffer) { + return consumed(this) || Promise.resolve(this._bodyArrayBuffer) + } else { + return this.blob().then(readBlobAsArrayBuffer) + } + } + } + + if (support.formData) { + this.formData = function() { + return this.text().then(decode) + } + } + + this.json = function() { + return this.text().then(JSON.parse) + } + + return this + } + + // HTTP methods whose capitalization should be normalized + var methods = ['DELETE', 'GET', 'HEAD', 'OPTIONS', 'POST', 'PUT'] + + function normalizeMethod(method) { + var upcased = method.toUpperCase() + return (methods.indexOf(upcased) > -1) ? upcased : method + } + + function Request(input, options) { + options = options || {} + var body = options.body + + if (typeof input === 'string') { + this.url = input + } else { + if (input.bodyUsed) { + throw new TypeError('Already read') + } + this.url = input.url + this.credentials = input.credentials + if (!options.headers) { + this.headers = new Headers(input.headers) + } + this.method = input.method + this.mode = input.mode + if (!body && input._bodyInit != null) { + body = input._bodyInit + input.bodyUsed = true + } + } + + this.credentials = options.credentials || this.credentials || 'omit' + if (options.headers || !this.headers) { + this.headers = new Headers(options.headers) + } + this.method = normalizeMethod(options.method || this.method || 'GET') + this.mode = options.mode || this.mode || null + this.referrer = null + + if ((this.method === 'GET' || this.method === 'HEAD') && body) { + throw new TypeError('Body not allowed for GET or HEAD requests') + } + this._initBody(body) + } + + Request.prototype.clone = function() { + return new Request(this, { body: this._bodyInit }) + } + + function decode(body) { + var form = new FormData() + body.trim().split('&').forEach(function(bytes) { + if (bytes) { + var split = bytes.split('=') + var name = split.shift().replace(/\+/g, ' ') + var value = split.join('=').replace(/\+/g, ' ') + form.append(decodeURIComponent(name), decodeURIComponent(value)) + } + }) + return form + } + + function parseHeaders(rawHeaders) { + var headers = new Headers() + rawHeaders.split('\r\n').forEach(function(line) { + var parts = line.split(':') + var key = parts.shift().trim() + if (key) { + var value = parts.join(':').trim() + headers.append(key, value) + } + }) + return headers + } + + Body.call(Request.prototype) + + function Response(bodyInit, options) { + if (!options) { + options = {} + } + + this.type = 'default' + this.status = 'status' in options ? options.status : 200 + this.ok = this.status >= 200 && this.status < 300 + this.statusText = 'statusText' in options ? options.statusText : 'OK' + this.headers = new Headers(options.headers) + this.url = options.url || '' + this._initBody(bodyInit) + } + + Body.call(Response.prototype) + + Response.prototype.clone = function() { + return new Response(this._bodyInit, { + status: this.status, + statusText: this.statusText, + headers: new Headers(this.headers), + url: this.url + }) + } + + Response.error = function() { + var response = new Response(null, {status: 0, statusText: ''}) + response.type = 'error' + return response + } + + var redirectStatuses = [301, 302, 303, 307, 308] + + Response.redirect = function(url, status) { + if (redirectStatuses.indexOf(status) === -1) { + throw new RangeError('Invalid status code') + } + + return new Response(null, {status: status, headers: {location: url}}) + } + + self.Headers = Headers + self.Request = Request + self.Response = Response + + self.fetch = function(input, init) { + return new Promise(function(resolve, reject) { + var request = new Request(input, init) + var xhr = new XMLHttpRequest() + + xhr.onload = function() { + var options = { + status: xhr.status, + statusText: xhr.statusText, + headers: parseHeaders(xhr.getAllResponseHeaders() || '') + } + options.url = 'responseURL' in xhr ? xhr.responseURL : options.headers.get('X-Request-URL') + var body = 'response' in xhr ? xhr.response : xhr.responseText + resolve(new Response(body, options)) + } + + xhr.onerror = function() { + reject(new TypeError('Network request failed')) + } + + xhr.ontimeout = function() { + reject(new TypeError('Network request failed')) + } + + xhr.open(request.method, request.url, true) + + if (request.credentials === 'include') { + xhr.withCredentials = true + } + + if ('responseType' in xhr && support.blob) { + xhr.responseType = 'blob' + } + + request.headers.forEach(function(value, name) { + xhr.setRequestHeader(name, value) + }) + + xhr.send(typeof request._bodyInit === 'undefined' ? null : request._bodyInit) + }) + } + self.fetch.polyfill = true +})(typeof self !== 'undefined' ? self : this); + +},{}]},{},[12])(12) +}); +//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIm5vZGVfbW9kdWxlcy9icm93c2VyLXBhY2svX3ByZWx1ZGUuanMiLCJsaWIvYXV0aC9iYXNpYy5qcyIsImxpYi9hdXRoL2luZGV4LmpzIiwibGliL2F1dGgvc2Vzc2lvbi5qcyIsImxpYi9hdXRoL3Rva2VuLmpzIiwibGliL2NsaWVudC5qcyIsImxpYi9jb2RlY3MvY29yZWpzb24uanMiLCJsaWIvY29kZWNzL2luZGV4LmpzIiwibGliL2NvZGVjcy9qc29uLmpzIiwibGliL2NvZGVjcy90ZXh0LmpzIiwibGliL2RvY3VtZW50LmpzIiwibGliL2Vycm9ycy5qcyIsImxpYi9pbmRleC5qcyIsImxpYi90cmFuc3BvcnRzL2h0dHAuanMiLCJsaWIvdHJhbnNwb3J0cy9pbmRleC5qcyIsImxpYi91dGlscy5qcyIsIm5vZGVfbW9kdWxlcy9pc29tb3JwaGljLWZldGNoL2ZldGNoLW5wbS1icm93c2VyaWZ5LmpzIiwibm9kZV9tb2R1bGVzL3F1ZXJ5c3RyaW5naWZ5L2luZGV4LmpzIiwibm9kZV9tb2R1bGVzL3JlcXVpcmVzLXBvcnQvaW5kZXguanMiLCJub2RlX21vZHVsZXMvdXJsLXBhcnNlL2luZGV4LmpzIiwibm9kZV9tb2R1bGVzL3VybC1wYXJzZS9sb2xjYXRpb24uanMiLCJub2RlX21vZHVsZXMvdXJsLXRlbXBsYXRlL2xpYi91cmwtdGVtcGxhdGUuanMiLCJub2RlX21vZHVsZXMvd2hhdHdnLWZldGNoL2ZldGNoLmpzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7O0lDQU0sbUI7QUFDSixpQ0FBMkI7QUFBQSxRQUFkLE9BQWMsdUVBQUosRUFBSTs7QUFBQTs7QUFDekIsUUFBTSxXQUFXLFFBQVEsUUFBekI7QUFDQSxRQUFNLFdBQVcsUUFBUSxRQUF6QjtBQUNBLFFBQU0sT0FBTyxPQUFPLElBQVAsQ0FBWSxXQUFXLEdBQVgsR0FBaUIsUUFBN0IsQ0FBYjtBQUNBLFNBQUssSUFBTCxHQUFZLFdBQVcsSUFBdkI7QUFDRDs7OztpQ0FFYSxPLEVBQVM7QUFDckIsY0FBUSxPQUFSLENBQWdCLGVBQWhCLElBQW1DLEtBQUssSUFBeEM7QUFDQSxhQUFPLE9BQVA7QUFDRDs7Ozs7O0FBR0gsT0FBTyxPQUFQLEdBQWlCO0FBQ2YsdUJBQXFCO0FBRE4sQ0FBakI7Ozs7O0FDZEEsSUFBTSxRQUFRLFFBQVEsU0FBUixDQUFkO0FBQ0EsSUFBTSxVQUFVLFFBQVEsV0FBUixDQUFoQjtBQUNBLElBQU0sUUFBUSxRQUFRLFNBQVIsQ0FBZDs7QUFFQSxPQUFPLE9BQVAsR0FBaUI7QUFDZix1QkFBcUIsTUFBTSxtQkFEWjtBQUVmLHlCQUF1QixRQUFRLHFCQUZoQjtBQUdmLHVCQUFxQixNQUFNO0FBSFosQ0FBakI7Ozs7Ozs7OztBQ0pBLElBQU0sUUFBUSxRQUFRLFVBQVIsQ0FBZDs7QUFFQSxTQUFTLElBQVQsQ0FBZSxHQUFmLEVBQW9CO0FBQ2xCLFNBQU8sSUFBSSxPQUFKLENBQVksUUFBWixFQUFzQixFQUF0QixFQUEwQixPQUExQixDQUFrQyxRQUFsQyxFQUE0QyxFQUE1QyxDQUFQO0FBQ0Q7O0FBRUQsU0FBUyxTQUFULENBQW9CLFVBQXBCLEVBQWdDLFlBQWhDLEVBQThDO0FBQzVDLGlCQUFlLGdCQUFnQixPQUFPLFFBQVAsQ0FBZ0IsTUFBL0M7QUFDQSxNQUFJLGdCQUFnQixpQkFBaUIsRUFBckMsRUFBeUM7QUFDdkMsUUFBTSxVQUFVLGFBQWEsS0FBYixDQUFtQixHQUFuQixDQUFoQjtBQUNBLFNBQUssSUFBSSxJQUFJLENBQWIsRUFBZ0IsSUFBSSxRQUFRLE1BQTVCLEVBQW9DLEdBQXBDLEVBQXlDO0FBQ3ZDLFVBQU0sU0FBUyxLQUFLLFFBQVEsQ0FBUixDQUFMLENBQWY7QUFDQTtBQUNBLFVBQUksT0FBTyxTQUFQLENBQWlCLENBQWpCLEVBQW9CLFdBQVcsTUFBWCxHQUFvQixDQUF4QyxNQUFnRCxhQUFhLEdBQWpFLEVBQXVFO0FBQ3JFLGVBQU8sbUJBQW1CLE9BQU8sU0FBUCxDQUFpQixXQUFXLE1BQVgsR0FBb0IsQ0FBckMsQ0FBbkIsQ0FBUDtBQUNEO0FBQ0Y7QUFDRjtBQUNELFNBQU8sSUFBUDtBQUNEOztJQUVLLHFCO0FBQ0osbUNBQTJCO0FBQUEsUUFBZCxPQUFjLHVFQUFKLEVBQUk7O0FBQUE7O0FBQ3pCLFNBQUssU0FBTCxHQUFpQixVQUFVLFFBQVEsY0FBbEIsRUFBa0MsUUFBUSxZQUExQyxDQUFqQjtBQUNBLFNBQUssY0FBTCxHQUFzQixRQUFRLGNBQTlCO0FBQ0Q7Ozs7aUNBRWEsTyxFQUFTO0FBQ3JCLGNBQVEsV0FBUixHQUFzQixhQUF0QjtBQUNBLFVBQUksS0FBSyxTQUFMLElBQWtCLENBQUMsTUFBTSxjQUFOLENBQXFCLFFBQVEsTUFBN0IsQ0FBdkIsRUFBNkQ7QUFDM0QsZ0JBQVEsT0FBUixDQUFnQixLQUFLLGNBQXJCLElBQXVDLEtBQUssU0FBNUM7QUFDRDtBQUNELGFBQU8sT0FBUDtBQUNEOzs7Ozs7QUFHSCxPQUFPLE9BQVAsR0FBaUI7QUFDZix5QkFBdUI7QUFEUixDQUFqQjs7Ozs7Ozs7O0lDcENNLG1CO0FBQ0osaUNBQTJCO0FBQUEsUUFBZCxPQUFjLHVFQUFKLEVBQUk7O0FBQUE7O0FBQ3pCLFNBQUssS0FBTCxHQUFhLFFBQVEsS0FBckI7QUFDQSxTQUFLLE1BQUwsR0FBYyxRQUFRLE1BQVIsSUFBa0IsUUFBaEM7QUFDRDs7OztpQ0FFYSxPLEVBQVM7QUFDckIsY0FBUSxPQUFSLENBQWdCLGVBQWhCLElBQW1DLEtBQUssTUFBTCxHQUFjLEdBQWQsR0FBb0IsS0FBSyxLQUE1RDtBQUNBLGFBQU8sT0FBUDtBQUNEOzs7Ozs7QUFHSCxPQUFPLE9BQVAsR0FBaUI7QUFDZix1QkFBcUI7QUFETixDQUFqQjs7Ozs7Ozs7O0FDWkEsSUFBTSxXQUFXLFFBQVEsWUFBUixDQUFqQjtBQUNBLElBQU0sU0FBUyxRQUFRLFVBQVIsQ0FBZjtBQUNBLElBQU0sU0FBUyxRQUFRLFVBQVIsQ0FBZjtBQUNBLElBQU0sYUFBYSxRQUFRLGNBQVIsQ0FBbkI7QUFDQSxJQUFNLFFBQVEsUUFBUSxTQUFSLENBQWQ7O0FBRUEsU0FBUyxVQUFULENBQXFCLElBQXJCLEVBQTJCLElBQTNCLEVBQWlDO0FBQUE7QUFBQTtBQUFBOztBQUFBO0FBQy9CLHlCQUFnQixJQUFoQiw4SEFBc0I7QUFBQSxVQUFiLEdBQWE7O0FBQ3BCLFVBQUksZ0JBQWdCLFNBQVMsUUFBN0IsRUFBdUM7QUFDckMsZUFBTyxLQUFLLE9BQUwsQ0FBYSxHQUFiLENBQVA7QUFDRCxPQUZELE1BRU87QUFDTCxlQUFPLEtBQUssR0FBTCxDQUFQO0FBQ0Q7QUFDRCxVQUFJLFNBQVMsU0FBYixFQUF3QjtBQUN0QixjQUFNLElBQUksT0FBTyxlQUFYLDJCQUFtRCxLQUFLLFNBQUwsQ0FBZSxJQUFmLENBQW5ELENBQU47QUFDRDtBQUNGO0FBVjhCO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7O0FBVy9CLE1BQUksRUFBRSxnQkFBZ0IsU0FBUyxJQUEzQixDQUFKLEVBQXNDO0FBQ3BDLFVBQU0sSUFBSSxPQUFPLGVBQVgsMkJBQW1ELEtBQUssU0FBTCxDQUFlLElBQWYsQ0FBbkQsQ0FBTjtBQUNEO0FBQ0QsU0FBTyxJQUFQO0FBQ0Q7O0lBRUssTTtBQUNKLG9CQUEyQjtBQUFBLFFBQWQsT0FBYyx1RUFBSixFQUFJOztBQUFBOztBQUN6QixRQUFNLG1CQUFtQjtBQUN2QixZQUFNLFFBQVEsSUFBUixJQUFnQixJQURDO0FBRXZCLGVBQVMsUUFBUSxPQUFSLElBQW1CLEVBRkw7QUFHdkIsdUJBQWlCLFFBQVEsZUFIRjtBQUl2Qix3QkFBa0IsUUFBUTtBQUpILEtBQXpCOztBQU9BLFNBQUssUUFBTCxHQUFnQixRQUFRLFFBQVIsSUFBb0IsQ0FBQyxJQUFJLE9BQU8sYUFBWCxFQUFELEVBQTZCLElBQUksT0FBTyxTQUFYLEVBQTdCLEVBQXFELElBQUksT0FBTyxTQUFYLEVBQXJELENBQXBDO0FBQ0EsU0FBSyxVQUFMLEdBQWtCLFFBQVEsVUFBUixJQUFzQixDQUFDLElBQUksV0FBVyxhQUFmLENBQTZCLGdCQUE3QixDQUFELENBQXhDO0FBQ0Q7Ozs7MkJBRU8sUSxFQUFVLEksRUFBbUI7QUFBQSxVQUFiLE1BQWEsdUVBQUosRUFBSTs7QUFDbkMsVUFBTSxPQUFPLFdBQVcsUUFBWCxFQUFxQixJQUFyQixDQUFiO0FBQ0EsVUFBTSxZQUFZLE1BQU0sa0JBQU4sQ0FBeUIsS0FBSyxVQUE5QixFQUEwQyxLQUFLLEdBQS9DLENBQWxCO0FBQ0EsYUFBTyxVQUFVLE1BQVYsQ0FBaUIsSUFBakIsRUFBdUIsS0FBSyxRQUE1QixFQUFzQyxNQUF0QyxDQUFQO0FBQ0Q7Ozt3QkFFSSxHLEVBQUs7QUFDUixVQUFNLE9BQU8sSUFBSSxTQUFTLElBQWIsQ0FBa0IsR0FBbEIsRUFBdUIsS0FBdkIsQ0FBYjtBQUNBLFVBQU0sWUFBWSxNQUFNLGtCQUFOLENBQXlCLEtBQUssVUFBOUIsRUFBMEMsR0FBMUMsQ0FBbEI7QUFDQSxhQUFPLFVBQVUsTUFBVixDQUFpQixJQUFqQixFQUF1QixLQUFLLFFBQTVCLENBQVA7QUFDRDs7Ozs7O0FBR0gsT0FBTyxPQUFQLEdBQWlCO0FBQ2YsVUFBUTtBQURPLENBQWpCOzs7Ozs7Ozs7OztBQ2pEQSxJQUFNLFdBQVcsUUFBUSxhQUFSLENBQWpCO0FBQ0EsSUFBTSxNQUFNLFFBQVEsV0FBUixDQUFaOztBQUVBLFNBQVMsV0FBVCxDQUFzQixHQUF0QixFQUEyQjtBQUN6QixNQUFJLElBQUksS0FBSixDQUFVLGdCQUFWLENBQUosRUFBaUM7QUFDL0IsV0FBTyxJQUFJLFNBQUosQ0FBYyxDQUFkLENBQVA7QUFDRDtBQUNELFNBQU8sR0FBUDtBQUNEOztBQUVELFNBQVMsU0FBVCxDQUFvQixHQUFwQixFQUF5QixHQUF6QixFQUE4QjtBQUM1QixNQUFNLFFBQVEsSUFBSSxHQUFKLENBQWQ7QUFDQSxNQUFJLE9BQVEsS0FBUixLQUFtQixRQUF2QixFQUFpQztBQUMvQixXQUFPLEtBQVA7QUFDRDtBQUNELFNBQU8sRUFBUDtBQUNEOztBQUVELFNBQVMsVUFBVCxDQUFxQixHQUFyQixFQUEwQixHQUExQixFQUErQjtBQUM3QixNQUFNLFFBQVEsSUFBSSxHQUFKLENBQWQ7QUFDQSxNQUFJLE9BQVEsS0FBUixLQUFtQixTQUF2QixFQUFrQztBQUNoQyxXQUFPLEtBQVA7QUFDRDtBQUNELFNBQU8sS0FBUDtBQUNEOztBQUVELFNBQVMsU0FBVCxDQUFvQixHQUFwQixFQUF5QixHQUF6QixFQUE4QjtBQUM1QixNQUFNLFFBQVEsSUFBSSxHQUFKLENBQWQ7QUFDQSxNQUFJLFFBQVEsS0FBUix5Q0FBUSxLQUFSLE9BQW1CLFFBQXZCLEVBQWlDO0FBQy9CLFdBQU8sS0FBUDtBQUNEO0FBQ0QsU0FBTyxFQUFQO0FBQ0Q7O0FBRUQsU0FBUyxRQUFULENBQW1CLEdBQW5CLEVBQXdCLEdBQXhCLEVBQTZCO0FBQzNCLE1BQU0sUUFBUSxJQUFJLEdBQUosQ0FBZDtBQUNBLE1BQUksaUJBQWlCLEtBQXJCLEVBQTRCO0FBQzFCLFdBQU8sS0FBUDtBQUNEO0FBQ0QsU0FBTyxFQUFQO0FBQ0Q7O0FBRUQsU0FBUyxVQUFULENBQXFCLElBQXJCLEVBQTJCLE9BQTNCLEVBQW9DO0FBQ2xDLE1BQU0sV0FBVyxDQUFDLE9BQUQsRUFBVSxPQUFWLENBQWpCO0FBQ0EsTUFBSSxVQUFVLEVBQWQ7QUFDQSxPQUFLLElBQUksUUFBVCxJQUFxQixJQUFyQixFQUEyQjtBQUN6QixRQUFJLEtBQUssY0FBTCxDQUFvQixRQUFwQixLQUFpQyxDQUFDLFNBQVMsUUFBVCxDQUFrQixRQUFsQixDQUF0QyxFQUFtRTtBQUNqRSxVQUFNLE1BQU0sWUFBWSxRQUFaLENBQVo7QUFDQSxVQUFNLFFBQVEsZ0JBQWdCLEtBQUssUUFBTCxDQUFoQixFQUFnQyxPQUFoQyxDQUFkO0FBQ0EsY0FBUSxHQUFSLElBQWUsS0FBZjtBQUNEO0FBQ0Y7QUFDRCxTQUFPLE9BQVA7QUFDRDs7QUFFRCxTQUFTLGVBQVQsQ0FBMEIsSUFBMUIsRUFBZ0MsT0FBaEMsRUFBeUM7QUFDdkMsTUFBTSxXQUFXLGdCQUFnQixNQUFoQixJQUEwQixFQUFFLGdCQUFnQixLQUFsQixDQUEzQzs7QUFFQSxNQUFJLFlBQVksS0FBSyxLQUFMLEtBQWUsVUFBL0IsRUFBMkM7QUFDekM7QUFDQSxRQUFNLE9BQU8sVUFBVSxJQUFWLEVBQWdCLE9BQWhCLENBQWI7QUFDQSxRQUFNLGNBQWMsVUFBVSxJQUFWLEVBQWdCLEtBQWhCLENBQXBCO0FBQ0EsUUFBTSxNQUFNLGNBQWMsSUFBSSxXQUFKLEVBQWlCLE9BQWpCLEVBQTBCLFFBQTFCLEVBQWQsR0FBcUQsRUFBakU7QUFDQSxRQUFNLFFBQVEsVUFBVSxJQUFWLEVBQWdCLE9BQWhCLENBQWQ7QUFDQSxRQUFNLGNBQWMsVUFBVSxJQUFWLEVBQWdCLGFBQWhCLENBQXBCO0FBQ0EsUUFBTSxVQUFVLFdBQVcsSUFBWCxFQUFpQixHQUFqQixDQUFoQjtBQUNBLFdBQU8sSUFBSSxTQUFTLFFBQWIsQ0FBc0IsR0FBdEIsRUFBMkIsS0FBM0IsRUFBa0MsV0FBbEMsRUFBK0MsT0FBL0MsQ0FBUDtBQUNELEdBVEQsTUFTTyxJQUFJLFlBQVksS0FBSyxLQUFMLEtBQWUsTUFBL0IsRUFBdUM7QUFDNUM7QUFDQSxRQUFNLGVBQWMsVUFBVSxJQUFWLEVBQWdCLEtBQWhCLENBQXBCO0FBQ0EsUUFBTSxPQUFNLGVBQWMsSUFBSSxZQUFKLEVBQWlCLE9BQWpCLEVBQTBCLFFBQTFCLEVBQWQsR0FBcUQsRUFBakU7QUFDQSxRQUFNLFNBQVMsVUFBVSxJQUFWLEVBQWdCLFFBQWhCLEtBQTZCLEtBQTVDO0FBQ0EsUUFBTSxTQUFRLFVBQVUsSUFBVixFQUFnQixPQUFoQixDQUFkO0FBQ0EsUUFBTSxlQUFjLFVBQVUsSUFBVixFQUFnQixhQUFoQixDQUFwQjtBQUNBLFFBQU0sYUFBYSxTQUFTLElBQVQsRUFBZSxRQUFmLENBQW5CO0FBQ0EsUUFBSSxTQUFTLEVBQWI7QUFDQSxTQUFLLElBQUksTUFBTSxDQUFWLEVBQWEsTUFBTSxXQUFXLE1BQW5DLEVBQTJDLE1BQU0sR0FBakQsRUFBc0QsS0FBdEQsRUFBNkQ7QUFDM0QsVUFBSSxRQUFRLFdBQVcsR0FBWCxDQUFaO0FBQ0EsVUFBSSxPQUFPLFVBQVUsS0FBVixFQUFpQixNQUFqQixDQUFYO0FBQ0EsVUFBSSxXQUFXLFdBQVcsS0FBWCxFQUFrQixVQUFsQixDQUFmO0FBQ0EsVUFBSSxXQUFXLFVBQVUsS0FBVixFQUFpQixVQUFqQixDQUFmO0FBQ0EsVUFBSSxtQkFBbUIsVUFBVSxLQUFWLEVBQWlCLGtCQUFqQixDQUF2QjtBQUNBLFVBQUksUUFBUSxJQUFJLFNBQVMsS0FBYixDQUFtQixJQUFuQixFQUF5QixRQUF6QixFQUFtQyxRQUFuQyxFQUE2QyxnQkFBN0MsQ0FBWjtBQUNBLGFBQU8sSUFBUCxDQUFZLEtBQVo7QUFDRDtBQUNELFdBQU8sSUFBSSxTQUFTLElBQWIsQ0FBa0IsSUFBbEIsRUFBdUIsTUFBdkIsRUFBK0Isa0JBQS9CLEVBQW1ELE1BQW5ELEVBQTJELE1BQTNELEVBQWtFLFlBQWxFLENBQVA7QUFDRCxHQW5CTSxNQW1CQSxJQUFJLFFBQUosRUFBYztBQUNuQjtBQUNBLFFBQUksV0FBVSxFQUFkO0FBQ0EsU0FBSyxJQUFJLEdBQVQsSUFBZ0IsSUFBaEIsRUFBc0I7QUFDcEIsVUFBSSxLQUFLLGNBQUwsQ0FBb0IsR0FBcEIsQ0FBSixFQUE4QjtBQUM1QixpQkFBUSxHQUFSLElBQWUsZ0JBQWdCLEtBQUssR0FBTCxDQUFoQixFQUEyQixPQUEzQixDQUFmO0FBQ0Q7QUFDRjtBQUNELFdBQU8sUUFBUDtBQUNELEdBVE0sTUFTQSxJQUFJLGdCQUFnQixLQUFwQixFQUEyQjtBQUNoQztBQUNBLFFBQUksWUFBVSxFQUFkO0FBQ0EsU0FBSyxJQUFJLE9BQU0sQ0FBVixFQUFhLE9BQU0sS0FBSyxNQUE3QixFQUFxQyxPQUFNLElBQTNDLEVBQWdELE1BQWhELEVBQXVEO0FBQ3JELGdCQUFRLElBQVIsQ0FBYSxnQkFBZ0IsS0FBSyxJQUFMLENBQWhCLEVBQTJCLE9BQTNCLENBQWI7QUFDRDtBQUNELFdBQU8sU0FBUDtBQUNEO0FBQ0Q7QUFDQSxTQUFPLElBQVA7QUFDRDs7SUFFSyxhO0FBQ0osMkJBQWU7QUFBQTs7QUFDYixTQUFLLFNBQUwsR0FBaUIsMEJBQWpCO0FBQ0Q7Ozs7MkJBRU8sSSxFQUFvQjtBQUFBLFVBQWQsT0FBYyx1RUFBSixFQUFJOztBQUMxQixVQUFJLE9BQU8sSUFBWDtBQUNBLFVBQUksUUFBUSxTQUFSLEtBQXNCLFNBQXRCLElBQW1DLENBQUMsUUFBUSxTQUFoRCxFQUEyRDtBQUN6RCxlQUFPLEtBQUssS0FBTCxDQUFXLElBQVgsQ0FBUDtBQUNEO0FBQ0QsYUFBTyxnQkFBZ0IsSUFBaEIsRUFBc0IsUUFBUSxHQUE5QixDQUFQO0FBQ0Q7Ozs7OztBQUdILE9BQU8sT0FBUCxHQUFpQjtBQUNmLGlCQUFlO0FBREEsQ0FBakI7Ozs7O0FDekhBLElBQU0sV0FBVyxRQUFRLFlBQVIsQ0FBakI7QUFDQSxJQUFNLE9BQU8sUUFBUSxRQUFSLENBQWI7QUFDQSxJQUFNLE9BQU8sUUFBUSxRQUFSLENBQWI7O0FBRUEsT0FBTyxPQUFQLEdBQWlCO0FBQ2YsaUJBQWUsU0FBUyxhQURUO0FBRWYsYUFBVyxLQUFLLFNBRkQ7QUFHZixhQUFXLEtBQUs7QUFIRCxDQUFqQjs7Ozs7Ozs7O0lDSk0sUztBQUNKLHVCQUFlO0FBQUE7O0FBQ2IsU0FBSyxTQUFMLEdBQWlCLGtCQUFqQjtBQUNEOzs7OzJCQUVPLEksRUFBb0I7QUFBQSxVQUFkLE9BQWMsdUVBQUosRUFBSTs7QUFDMUIsYUFBTyxLQUFLLEtBQUwsQ0FBVyxJQUFYLENBQVA7QUFDRDs7Ozs7O0FBR0gsT0FBTyxPQUFQLEdBQWlCO0FBQ2YsYUFBVztBQURJLENBQWpCOzs7Ozs7Ozs7SUNWTSxTO0FBQ0osdUJBQWU7QUFBQTs7QUFDYixTQUFLLFNBQUwsR0FBaUIsUUFBakI7QUFDRDs7OzsyQkFFTyxJLEVBQW9CO0FBQUEsVUFBZCxPQUFjLHVFQUFKLEVBQUk7O0FBQzFCLGFBQU8sSUFBUDtBQUNEOzs7Ozs7QUFHSCxPQUFPLE9BQVAsR0FBaUI7QUFDZixhQUFXO0FBREksQ0FBakI7Ozs7Ozs7SUNWTSxRLEdBQ0osb0JBQW1FO0FBQUEsTUFBdEQsR0FBc0QsdUVBQWhELEVBQWdEO0FBQUEsTUFBNUMsS0FBNEMsdUVBQXBDLEVBQW9DO0FBQUEsTUFBaEMsV0FBZ0MsdUVBQWxCLEVBQWtCO0FBQUEsTUFBZCxPQUFjLHVFQUFKLEVBQUk7O0FBQUE7O0FBQ2pFLE9BQUssR0FBTCxHQUFXLEdBQVg7QUFDQSxPQUFLLEtBQUwsR0FBYSxLQUFiO0FBQ0EsT0FBSyxXQUFMLEdBQW1CLFdBQW5CO0FBQ0EsT0FBSyxPQUFMLEdBQWUsT0FBZjtBQUNELEM7O0lBR0csSSxHQUNKLGNBQWEsR0FBYixFQUFrQixNQUFsQixFQUFvRztBQUFBLE1BQTFFLFFBQTBFLHVFQUEvRCxrQkFBK0Q7QUFBQSxNQUEzQyxNQUEyQyx1RUFBbEMsRUFBa0M7QUFBQSxNQUE5QixLQUE4Qix1RUFBdEIsRUFBc0I7QUFBQSxNQUFsQixXQUFrQix1RUFBSixFQUFJOztBQUFBOztBQUNsRyxNQUFJLFFBQVEsU0FBWixFQUF1QjtBQUNyQixVQUFNLElBQUksS0FBSixDQUFVLDBCQUFWLENBQU47QUFDRDs7QUFFRCxNQUFJLFdBQVcsU0FBZixFQUEwQjtBQUN4QixVQUFNLElBQUksS0FBSixDQUFVLDZCQUFWLENBQU47QUFDRDs7QUFFRCxPQUFLLEdBQUwsR0FBVyxHQUFYO0FBQ0EsT0FBSyxNQUFMLEdBQWMsTUFBZDtBQUNBLE9BQUssUUFBTCxHQUFnQixRQUFoQjtBQUNBLE9BQUssTUFBTCxHQUFjLE1BQWQ7QUFDQSxPQUFLLEtBQUwsR0FBYSxLQUFiO0FBQ0EsT0FBSyxXQUFMLEdBQW1CLFdBQW5CO0FBQ0QsQzs7SUFHRyxLLEdBQ0osZUFBYSxJQUFiLEVBQXNFO0FBQUEsTUFBbkQsUUFBbUQsdUVBQXhDLEtBQXdDO0FBQUEsTUFBakMsUUFBaUMsdUVBQXRCLEVBQXNCO0FBQUEsTUFBbEIsV0FBa0IsdUVBQUosRUFBSTs7QUFBQTs7QUFDcEUsTUFBSSxTQUFTLFNBQWIsRUFBd0I7QUFDdEIsVUFBTSxJQUFJLEtBQUosQ0FBVSwyQkFBVixDQUFOO0FBQ0Q7O0FBRUQsT0FBSyxJQUFMLEdBQVksSUFBWjtBQUNBLE9BQUssUUFBTCxHQUFnQixRQUFoQjtBQUNBLE9BQUssUUFBTCxHQUFnQixRQUFoQjtBQUNBLE9BQUssV0FBTCxHQUFtQixXQUFuQjtBQUNELEM7O0FBR0gsT0FBTyxPQUFQLEdBQWlCO0FBQ2YsWUFBVSxRQURLO0FBRWYsUUFBTSxJQUZTO0FBR2YsU0FBTztBQUhRLENBQWpCOzs7Ozs7Ozs7OztJQ3pDTSxjOzs7QUFDSiwwQkFBYSxPQUFiLEVBQXNCO0FBQUE7O0FBQUEsZ0lBQ2QsT0FEYzs7QUFFcEIsVUFBSyxPQUFMLEdBQWUsT0FBZjtBQUNBLFVBQUssSUFBTCxHQUFZLGdCQUFaO0FBSG9CO0FBSXJCOzs7RUFMMEIsSzs7SUFRdkIsZTs7O0FBQ0osMkJBQWEsT0FBYixFQUFzQjtBQUFBOztBQUFBLG1JQUNkLE9BRGM7O0FBRXBCLFdBQUssT0FBTCxHQUFlLE9BQWY7QUFDQSxXQUFLLElBQUwsR0FBWSxpQkFBWjtBQUhvQjtBQUlyQjs7O0VBTDJCLEs7O0lBUXhCLFk7OztBQUNKLHdCQUFhLE9BQWIsRUFBc0IsT0FBdEIsRUFBK0I7QUFBQTs7QUFBQSw2SEFDdkIsT0FEdUI7O0FBRTdCLFdBQUssT0FBTCxHQUFlLE9BQWY7QUFDQSxXQUFLLE9BQUwsR0FBZSxPQUFmO0FBQ0EsV0FBSyxJQUFMLEdBQVksY0FBWjtBQUo2QjtBQUs5Qjs7O0VBTndCLEs7O0FBUzNCLE9BQU8sT0FBUCxHQUFpQjtBQUNmLGtCQUFnQixjQUREO0FBRWYsbUJBQWlCLGVBRkY7QUFHZixnQkFBYztBQUhDLENBQWpCOzs7OztBQ3pCQSxJQUFNLE9BQU8sUUFBUSxRQUFSLENBQWI7QUFDQSxJQUFNLFNBQVMsUUFBUSxVQUFSLENBQWY7QUFDQSxJQUFNLFNBQVMsUUFBUSxVQUFSLENBQWY7QUFDQSxJQUFNLFdBQVcsUUFBUSxZQUFSLENBQWpCO0FBQ0EsSUFBTSxTQUFTLFFBQVEsVUFBUixDQUFmO0FBQ0EsSUFBTSxhQUFhLFFBQVEsY0FBUixDQUFuQjtBQUNBLElBQU0sUUFBUSxRQUFRLFNBQVIsQ0FBZDs7QUFFQSxJQUFNLFVBQVU7QUFDZCxVQUFRLE9BQU8sTUFERDtBQUVkLFlBQVUsU0FBUyxRQUZMO0FBR2QsUUFBTSxTQUFTLElBSEQ7QUFJZCxRQUFNLElBSlE7QUFLZCxVQUFRLE1BTE07QUFNZCxVQUFRLE1BTk07QUFPZCxjQUFZLFVBUEU7QUFRZCxTQUFPO0FBUk8sQ0FBaEI7O0FBV0EsT0FBTyxPQUFQLEdBQWlCLE9BQWpCOzs7Ozs7Ozs7QUNuQkEsSUFBTSxRQUFRLFFBQVEsa0JBQVIsQ0FBZDtBQUNBLElBQU0sU0FBUyxRQUFRLFdBQVIsQ0FBZjtBQUNBLElBQU0sUUFBUSxRQUFRLFVBQVIsQ0FBZDtBQUNBLElBQU0sTUFBTSxRQUFRLFdBQVIsQ0FBWjtBQUNBLElBQU0sY0FBYyxRQUFRLGNBQVIsQ0FBcEI7O0FBRUEsSUFBTSxnQkFBZ0IsU0FBaEIsYUFBZ0IsQ0FBQyxRQUFELEVBQVcsUUFBWCxFQUFxQixnQkFBckIsRUFBMEM7QUFDOUQsU0FBTyxTQUFTLElBQVQsR0FBZ0IsSUFBaEIsQ0FBcUIsZ0JBQVE7QUFDbEMsUUFBSSxnQkFBSixFQUFzQjtBQUNwQix1QkFBaUIsUUFBakIsRUFBMkIsSUFBM0I7QUFDRDtBQUNELFFBQU0sY0FBYyxTQUFTLE9BQVQsQ0FBaUIsR0FBakIsQ0FBcUIsY0FBckIsQ0FBcEI7QUFDQSxRQUFNLFVBQVUsTUFBTSxnQkFBTixDQUF1QixRQUF2QixFQUFpQyxXQUFqQyxDQUFoQjtBQUNBLFFBQU0sVUFBVSxFQUFDLEtBQUssU0FBUyxHQUFmLEVBQWhCO0FBQ0EsV0FBTyxRQUFRLE1BQVIsQ0FBZSxJQUFmLEVBQXFCLE9BQXJCLENBQVA7QUFDRCxHQVJNLENBQVA7QUFTRCxDQVZEOztJQVlNLGE7QUFDSiwyQkFBMkI7QUFBQSxRQUFkLE9BQWMsdUVBQUosRUFBSTs7QUFBQTs7QUFDekIsU0FBSyxPQUFMLEdBQWUsQ0FBQyxNQUFELEVBQVMsT0FBVCxDQUFmO0FBQ0EsU0FBSyxJQUFMLEdBQVksUUFBUSxJQUFSLElBQWdCLElBQTVCO0FBQ0EsU0FBSyxPQUFMLEdBQWUsUUFBUSxPQUFSLElBQW1CLEVBQWxDO0FBQ0EsU0FBSyxLQUFMLEdBQWEsUUFBUSxLQUFSLElBQWlCLEtBQTlCO0FBQ0EsU0FBSyxRQUFMLEdBQWdCLFFBQVEsUUFBUixJQUFvQixPQUFPLFFBQTNDO0FBQ0EsU0FBSyxlQUFMLEdBQXVCLFFBQVEsZUFBL0I7QUFDQSxTQUFLLGdCQUFMLEdBQXdCLFFBQVEsZ0JBQWhDO0FBQ0Q7Ozs7aUNBRWEsSSxFQUFNLFEsRUFBdUI7QUFBQSxVQUFiLE1BQWEsdUVBQUosRUFBSTs7QUFDekMsVUFBTSxTQUFTLEtBQUssTUFBcEI7QUFDQSxVQUFNLFNBQVMsS0FBSyxNQUFMLENBQVksV0FBWixFQUFmO0FBQ0EsVUFBSSxjQUFjLEVBQWxCO0FBQ0EsVUFBSSxhQUFhLEVBQWpCO0FBQ0EsVUFBSSxhQUFhLEVBQWpCO0FBQ0EsVUFBSSxhQUFhLEVBQWpCO0FBQ0EsVUFBSSxVQUFVLEtBQWQ7O0FBRUEsV0FBSyxJQUFJLE1BQU0sQ0FBVixFQUFhLE1BQU0sT0FBTyxNQUEvQixFQUF1QyxNQUFNLEdBQTdDLEVBQWtELEtBQWxELEVBQXlEO0FBQ3ZELFlBQU0sUUFBUSxPQUFPLEdBQVAsQ0FBZDs7QUFFQTtBQUNBLFlBQUksQ0FBQyxPQUFPLGNBQVAsQ0FBc0IsTUFBTSxJQUE1QixDQUFMLEVBQXdDO0FBQ3RDLGNBQUksTUFBTSxRQUFWLEVBQW9CO0FBQ2xCLGtCQUFNLElBQUksT0FBTyxjQUFYLCtCQUFzRCxNQUFNLElBQTVELE9BQU47QUFDRCxXQUZELE1BRU87QUFDTDtBQUNEO0FBQ0Y7O0FBRUQsbUJBQVcsSUFBWCxDQUFnQixNQUFNLElBQXRCO0FBQ0EsWUFBSSxNQUFNLFFBQU4sS0FBbUIsT0FBdkIsRUFBZ0M7QUFDOUIsc0JBQVksTUFBTSxJQUFsQixJQUEwQixPQUFPLE1BQU0sSUFBYixDQUExQjtBQUNELFNBRkQsTUFFTyxJQUFJLE1BQU0sUUFBTixLQUFtQixNQUF2QixFQUErQjtBQUNwQyxxQkFBVyxNQUFNLElBQWpCLElBQXlCLE9BQU8sTUFBTSxJQUFiLENBQXpCO0FBQ0QsU0FGTSxNQUVBLElBQUksTUFBTSxRQUFOLEtBQW1CLE1BQXZCLEVBQStCO0FBQ3BDLHFCQUFXLE1BQU0sSUFBakIsSUFBeUIsT0FBTyxNQUFNLElBQWIsQ0FBekI7QUFDQSxvQkFBVSxJQUFWO0FBQ0QsU0FITSxNQUdBLElBQUksTUFBTSxRQUFOLEtBQW1CLE1BQXZCLEVBQStCO0FBQ3BDLHVCQUFhLE9BQU8sTUFBTSxJQUFiLENBQWI7QUFDQSxvQkFBVSxJQUFWO0FBQ0Q7QUFDRjs7QUFFRDtBQUNBLFdBQUssSUFBSSxRQUFULElBQXFCLE1BQXJCLEVBQTZCO0FBQzNCLFlBQUksT0FBTyxjQUFQLENBQXNCLFFBQXRCLEtBQW1DLENBQUMsV0FBVyxRQUFYLENBQW9CLFFBQXBCLENBQXhDLEVBQXVFO0FBQ3JFLGdCQUFNLElBQUksT0FBTyxjQUFYLDBCQUFpRCxRQUFqRCxPQUFOO0FBQ0Q7QUFDRjs7QUFFRCxVQUFJLGlCQUFpQixFQUFDLFFBQVEsTUFBVCxFQUFpQixTQUFTLEVBQTFCLEVBQXJCOztBQUVBLGFBQU8sTUFBUCxDQUFjLGVBQWUsT0FBN0IsRUFBc0MsS0FBSyxPQUEzQzs7QUFFQSxVQUFJLE9BQUosRUFBYTtBQUNYLFlBQUksS0FBSyxRQUFMLEtBQWtCLGtCQUF0QixFQUEwQztBQUN4Qyx5QkFBZSxJQUFmLEdBQXNCLEtBQUssU0FBTCxDQUFlLFVBQWYsQ0FBdEI7QUFDQSx5QkFBZSxPQUFmLENBQXVCLGNBQXZCLElBQXlDLGtCQUF6QztBQUNELFNBSEQsTUFHTyxJQUFJLEtBQUssUUFBTCxLQUFrQixxQkFBdEIsRUFBNkM7QUFDbEQsY0FBSSxPQUFPLElBQUksS0FBSyxRQUFULEVBQVg7O0FBRUEsZUFBSyxJQUFJLFFBQVQsSUFBcUIsVUFBckIsRUFBaUM7QUFDL0IsaUJBQUssTUFBTCxDQUFZLFFBQVosRUFBc0IsV0FBVyxRQUFYLENBQXRCO0FBQ0Q7QUFDRCx5QkFBZSxJQUFmLEdBQXNCLElBQXRCO0FBQ0QsU0FQTSxNQU9BLElBQUksS0FBSyxRQUFMLEtBQWtCLG1DQUF0QixFQUEyRDtBQUNoRSxjQUFJLFdBQVcsRUFBZjtBQUNBLGVBQUssSUFBSSxTQUFULElBQXFCLFVBQXJCLEVBQWlDO0FBQy9CLGdCQUFNLGFBQWEsbUJBQW1CLFNBQW5CLENBQW5CO0FBQ0EsZ0JBQU0sZUFBZSxtQkFBbUIsV0FBVyxTQUFYLENBQW5CLENBQXJCO0FBQ0EscUJBQVMsSUFBVCxDQUFjLGFBQWEsR0FBYixHQUFtQixZQUFqQztBQUNEO0FBQ0QscUJBQVcsU0FBUyxJQUFULENBQWMsR0FBZCxDQUFYOztBQUVBLHlCQUFlLElBQWYsR0FBc0IsUUFBdEI7QUFDQSx5QkFBZSxPQUFmLENBQXVCLGNBQXZCLElBQXlDLG1DQUF6QztBQUNEO0FBQ0Y7O0FBRUQsVUFBSSxLQUFLLElBQVQsRUFBZTtBQUNiLHlCQUFpQixLQUFLLElBQUwsQ0FBVSxZQUFWLENBQXVCLGNBQXZCLENBQWpCO0FBQ0Q7O0FBRUQsVUFBSSxZQUFZLFlBQVksS0FBWixDQUFrQixLQUFLLEdBQXZCLENBQWhCO0FBQ0Esa0JBQVksVUFBVSxNQUFWLENBQWlCLFVBQWpCLENBQVo7QUFDQSxrQkFBWSxJQUFJLEdBQUosQ0FBUSxTQUFSLENBQVo7QUFDQSxnQkFBVSxHQUFWLENBQWMsT0FBZCxFQUF1QixXQUF2Qjs7QUFFQSxhQUFPO0FBQ0wsYUFBSyxVQUFVLFFBQVYsRUFEQTtBQUVMLGlCQUFTO0FBRkosT0FBUDtBQUlEOzs7MkJBRU8sSSxFQUFNLFEsRUFBdUI7QUFBQSxVQUFiLE1BQWEsdUVBQUosRUFBSTs7QUFDbkMsVUFBTSxtQkFBbUIsS0FBSyxnQkFBOUI7QUFDQSxVQUFNLFVBQVUsS0FBSyxZQUFMLENBQWtCLElBQWxCLEVBQXdCLFFBQXhCLEVBQWtDLE1BQWxDLENBQWhCOztBQUVBLFVBQUksS0FBSyxlQUFULEVBQTBCO0FBQ3hCLGFBQUssZUFBTCxDQUFxQixPQUFyQjtBQUNEOztBQUVELGFBQU8sS0FBSyxLQUFMLENBQVcsUUFBUSxHQUFuQixFQUF3QixRQUFRLE9BQWhDLEVBQ0osSUFESSxDQUNDLFVBQVUsUUFBVixFQUFvQjtBQUN4QixZQUFJLFNBQVMsTUFBVCxLQUFvQixHQUF4QixFQUE2QjtBQUMzQjtBQUNEO0FBQ0QsZUFBTyxjQUFjLFFBQWQsRUFBd0IsUUFBeEIsRUFBa0MsZ0JBQWxDLEVBQ0osSUFESSxDQUNDLFVBQVUsSUFBVixFQUFnQjtBQUNwQixjQUFJLFNBQVMsRUFBYixFQUFpQjtBQUNmLG1CQUFPLElBQVA7QUFDRCxXQUZELE1BRU87QUFDTCxnQkFBTSxRQUFRLFNBQVMsTUFBVCxHQUFrQixHQUFsQixHQUF3QixTQUFTLFVBQS9DO0FBQ0EsZ0JBQU0sUUFBUSxJQUFJLE9BQU8sWUFBWCxDQUF3QixLQUF4QixFQUErQixJQUEvQixDQUFkO0FBQ0EsbUJBQU8sUUFBUSxNQUFSLENBQWUsS0FBZixDQUFQO0FBQ0Q7QUFDRixTQVRJLENBQVA7QUFVRCxPQWZJLENBQVA7QUFnQkQ7Ozs7OztBQUdILE9BQU8sT0FBUCxHQUFpQjtBQUNmLGlCQUFlO0FBREEsQ0FBakI7Ozs7O0FDOUlBLElBQU0sT0FBTyxRQUFRLFFBQVIsQ0FBYjs7QUFFQSxPQUFPLE9BQVAsR0FBaUI7QUFDZixpQkFBZSxLQUFLO0FBREwsQ0FBakI7Ozs7O0FDRkEsSUFBTSxNQUFNLFFBQVEsV0FBUixDQUFaOztBQUVBLElBQU0scUJBQXFCLFNBQXJCLGtCQUFxQixDQUFVLFVBQVYsRUFBc0IsR0FBdEIsRUFBMkI7QUFDcEQsTUFBTSxZQUFZLElBQUksR0FBSixDQUFRLEdBQVIsQ0FBbEI7QUFDQSxNQUFNLFNBQVMsVUFBVSxRQUFWLENBQW1CLE9BQW5CLENBQTJCLEdBQTNCLEVBQWdDLEVBQWhDLENBQWY7O0FBRm9EO0FBQUE7QUFBQTs7QUFBQTtBQUlwRCx5QkFBc0IsVUFBdEIsOEhBQWtDO0FBQUEsVUFBekIsU0FBeUI7O0FBQ2hDLFVBQUksVUFBVSxPQUFWLENBQWtCLFFBQWxCLENBQTJCLE1BQTNCLENBQUosRUFBd0M7QUFDdEMsZUFBTyxTQUFQO0FBQ0Q7QUFDRjtBQVJtRDtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBOztBQVVwRCxRQUFNLHNDQUFvQyxHQUFwQyxDQUFOO0FBQ0QsQ0FYRDs7QUFhQSxJQUFNLG1CQUFtQixTQUFuQixnQkFBbUIsQ0FBVSxRQUFWLEVBQW9CLFdBQXBCLEVBQWlDO0FBQ3hELE1BQUksZ0JBQWdCLFNBQWhCLElBQTZCLGdCQUFnQixJQUFqRCxFQUF1RDtBQUNyRCxXQUFPLFNBQVMsQ0FBVCxDQUFQO0FBQ0Q7O0FBRUQsTUFBTSxXQUFXLFlBQVksV0FBWixHQUEwQixLQUExQixDQUFnQyxHQUFoQyxFQUFxQyxDQUFyQyxFQUF3QyxJQUF4QyxFQUFqQjtBQUNBLE1BQU0sV0FBVyxTQUFTLEtBQVQsQ0FBZSxHQUFmLEVBQW9CLENBQXBCLElBQXlCLElBQTFDO0FBQ0EsTUFBTSxlQUFlLEtBQXJCO0FBQ0EsTUFBTSxrQkFBa0IsQ0FBQyxRQUFELEVBQVcsUUFBWCxFQUFxQixZQUFyQixDQUF4Qjs7QUFSd0Q7QUFBQTtBQUFBOztBQUFBO0FBVXhELDBCQUFvQixRQUFwQixtSUFBOEI7QUFBQSxVQUFyQixPQUFxQjs7QUFDNUIsVUFBSSxnQkFBZ0IsUUFBaEIsQ0FBeUIsUUFBUSxTQUFqQyxDQUFKLEVBQWlEO0FBQy9DLGVBQU8sT0FBUDtBQUNEO0FBQ0Y7QUFkdUQ7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTs7QUFnQnhELFFBQU0scURBQW1ELFdBQW5ELENBQU47QUFDRCxDQWpCRDs7QUFtQkEsSUFBTSxpQkFBaUIsU0FBakIsY0FBaUIsQ0FBVSxNQUFWLEVBQWtCO0FBQ3ZDO0FBQ0EsU0FBUSw4QkFBNkIsSUFBN0IsQ0FBa0MsTUFBbEM7QUFBUjtBQUNELENBSEQ7O0FBS0EsT0FBTyxPQUFQLEdBQWlCO0FBQ2Ysc0JBQW9CLGtCQURMO0FBRWYsb0JBQWtCLGdCQUZIO0FBR2Ysa0JBQWdCO0FBSEQsQ0FBakI7OztBQ3ZDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTs7QUNOQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBOztBQzdEQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7O0FDdENBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBOzs7QUNyV0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBOzs7O0FDckRBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBOztBQ2hNQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0E7QUFDQTtBQUNBO0FBQ0EiLCJmaWxlIjoiZ2VuZXJhdGVkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXNDb250ZW50IjpbIihmdW5jdGlvbiBlKHQsbixyKXtmdW5jdGlvbiBzKG8sdSl7aWYoIW5bb10pe2lmKCF0W29dKXt2YXIgYT10eXBlb2YgcmVxdWlyZT09XCJmdW5jdGlvblwiJiZyZXF1aXJlO2lmKCF1JiZhKXJldHVybiBhKG8sITApO2lmKGkpcmV0dXJuIGkobywhMCk7dmFyIGY9bmV3IEVycm9yKFwiQ2Fubm90IGZpbmQgbW9kdWxlICdcIitvK1wiJ1wiKTt0aHJvdyBmLmNvZGU9XCJNT0RVTEVfTk9UX0ZPVU5EXCIsZn12YXIgbD1uW29dPXtleHBvcnRzOnt9fTt0W29dWzBdLmNhbGwobC5leHBvcnRzLGZ1bmN0aW9uKGUpe3ZhciBuPXRbb11bMV1bZV07cmV0dXJuIHMobj9uOmUpfSxsLGwuZXhwb3J0cyxlLHQsbixyKX1yZXR1cm4gbltvXS5leHBvcnRzfXZhciBpPXR5cGVvZiByZXF1aXJlPT1cImZ1bmN0aW9uXCImJnJlcXVpcmU7Zm9yKHZhciBvPTA7bzxyLmxlbmd0aDtvKyspcyhyW29dKTtyZXR1cm4gc30pIiwiY2xhc3MgQmFzaWNBdXRoZW50aWNhdGlvbiB7XG4gIGNvbnN0cnVjdG9yIChvcHRpb25zID0ge30pIHtcbiAgICBjb25zdCB1c2VybmFtZSA9IG9wdGlvbnMudXNlcm5hbWVcbiAgICBjb25zdCBwYXNzd29yZCA9IG9wdGlvbnMucGFzc3dvcmRcbiAgICBjb25zdCBoYXNoID0gd2luZG93LmJ0b2EodXNlcm5hbWUgKyAnOicgKyBwYXNzd29yZClcbiAgICB0aGlzLmF1dGggPSAnQmFzaWMgJyArIGhhc2hcbiAgfVxuXG4gIGF1dGhlbnRpY2F0ZSAob3B0aW9ucykge1xuICAgIG9wdGlvbnMuaGVhZGVyc1snQXV0aG9yaXphdGlvbiddID0gdGhpcy5hdXRoXG4gICAgcmV0dXJuIG9wdGlvbnNcbiAgfVxufVxuXG5tb2R1bGUuZXhwb3J0cyA9IHtcbiAgQmFzaWNBdXRoZW50aWNhdGlvbjogQmFzaWNBdXRoZW50aWNhdGlvblxufVxuIiwiY29uc3QgYmFzaWMgPSByZXF1aXJlKCcuL2Jhc2ljJylcbmNvbnN0IHNlc3Npb24gPSByZXF1aXJlKCcuL3Nlc3Npb24nKVxuY29uc3QgdG9rZW4gPSByZXF1aXJlKCcuL3Rva2VuJylcblxubW9kdWxlLmV4cG9ydHMgPSB7XG4gIEJhc2ljQXV0aGVudGljYXRpb246IGJhc2ljLkJhc2ljQXV0aGVudGljYXRpb24sXG4gIFNlc3Npb25BdXRoZW50aWNhdGlvbjogc2Vzc2lvbi5TZXNzaW9uQXV0aGVudGljYXRpb24sXG4gIFRva2VuQXV0aGVudGljYXRpb246IHRva2VuLlRva2VuQXV0aGVudGljYXRpb25cbn1cbiIsImNvbnN0IHV0aWxzID0gcmVxdWlyZSgnLi4vdXRpbHMnKVxuXG5mdW5jdGlvbiB0cmltIChzdHIpIHtcbiAgcmV0dXJuIHN0ci5yZXBsYWNlKC9eXFxzXFxzKi8sICcnKS5yZXBsYWNlKC9cXHNcXHMqJC8sICcnKVxufVxuXG5mdW5jdGlvbiBnZXRDb29raWUgKGNvb2tpZU5hbWUsIGNvb2tpZVN0cmluZykge1xuICBjb29raWVTdHJpbmcgPSBjb29raWVTdHJpbmcgfHwgd2luZG93LmRvY3VtZW50LmNvb2tpZVxuICBpZiAoY29va2llU3RyaW5nICYmIGNvb2tpZVN0cmluZyAhPT0gJycpIHtcbiAgICBjb25zdCBjb29raWVzID0gY29va2llU3RyaW5nLnNwbGl0KCc7JylcbiAgICBmb3IgKHZhciBpID0gMDsgaSA8IGNvb2tpZXMubGVuZ3RoOyBpKyspIHtcbiAgICAgIGNvbnN0IGNvb2tpZSA9IHRyaW0oY29va2llc1tpXSlcbiAgICAgIC8vIERvZXMgdGhpcyBjb29raWUgc3RyaW5nIGJlZ2luIHdpdGggdGhlIG5hbWUgd2Ugd2FudD9cbiAgICAgIGlmIChjb29raWUuc3Vic3RyaW5nKDAsIGNvb2tpZU5hbWUubGVuZ3RoICsgMSkgPT09IChjb29raWVOYW1lICsgJz0nKSkge1xuICAgICAgICByZXR1cm4gZGVjb2RlVVJJQ29tcG9uZW50KGNvb2tpZS5zdWJzdHJpbmcoY29va2llTmFtZS5sZW5ndGggKyAxKSlcbiAgICAgIH1cbiAgICB9XG4gIH1cbiAgcmV0dXJuIG51bGxcbn1cblxuY2xhc3MgU2Vzc2lvbkF1dGhlbnRpY2F0aW9uIHtcbiAgY29uc3RydWN0b3IgKG9wdGlvbnMgPSB7fSkge1xuICAgIHRoaXMuY3NyZlRva2VuID0gZ2V0Q29va2llKG9wdGlvbnMuY3NyZkNvb2tpZU5hbWUsIG9wdGlvbnMuY29va2llU3RyaW5nKVxuICAgIHRoaXMuY3NyZkhlYWRlck5hbWUgPSBvcHRpb25zLmNzcmZIZWFkZXJOYW1lXG4gIH1cblxuICBhdXRoZW50aWNhdGUgKG9wdGlvbnMpIHtcbiAgICBvcHRpb25zLmNyZWRlbnRpYWxzID0gJ3NhbWUtb3JpZ2luJ1xuICAgIGlmICh0aGlzLmNzcmZUb2tlbiAmJiAhdXRpbHMuY3NyZlNhZmVNZXRob2Qob3B0aW9ucy5tZXRob2QpKSB7XG4gICAgICBvcHRpb25zLmhlYWRlcnNbdGhpcy5jc3JmSGVhZGVyTmFtZV0gPSB0aGlzLmNzcmZUb2tlblxuICAgIH1cbiAgICByZXR1cm4gb3B0aW9uc1xuICB9XG59XG5cbm1vZHVsZS5leHBvcnRzID0ge1xuICBTZXNzaW9uQXV0aGVudGljYXRpb246IFNlc3Npb25BdXRoZW50aWNhdGlvblxufVxuIiwiY2xhc3MgVG9rZW5BdXRoZW50aWNhdGlvbiB7XG4gIGNvbnN0cnVjdG9yIChvcHRpb25zID0ge30pIHtcbiAgICB0aGlzLnRva2VuID0gb3B0aW9ucy50b2tlblxuICAgIHRoaXMuc2NoZW1lID0gb3B0aW9ucy5zY2hlbWUgfHwgJ0JlYXJlcidcbiAgfVxuXG4gIGF1dGhlbnRpY2F0ZSAob3B0aW9ucykge1xuICAgIG9wdGlvbnMuaGVhZGVyc1snQXV0aG9yaXphdGlvbiddID0gdGhpcy5zY2hlbWUgKyAnICcgKyB0aGlzLnRva2VuXG4gICAgcmV0dXJuIG9wdGlvbnNcbiAgfVxufVxuXG5tb2R1bGUuZXhwb3J0cyA9IHtcbiAgVG9rZW5BdXRoZW50aWNhdGlvbjogVG9rZW5BdXRoZW50aWNhdGlvblxufVxuIiwiY29uc3QgZG9jdW1lbnQgPSByZXF1aXJlKCcuL2RvY3VtZW50JylcbmNvbnN0IGNvZGVjcyA9IHJlcXVpcmUoJy4vY29kZWNzJylcbmNvbnN0IGVycm9ycyA9IHJlcXVpcmUoJy4vZXJyb3JzJylcbmNvbnN0IHRyYW5zcG9ydHMgPSByZXF1aXJlKCcuL3RyYW5zcG9ydHMnKVxuY29uc3QgdXRpbHMgPSByZXF1aXJlKCcuL3V0aWxzJylcblxuZnVuY3Rpb24gbG9va3VwTGluayAobm9kZSwga2V5cykge1xuICBmb3IgKGxldCBrZXkgb2Yga2V5cykge1xuICAgIGlmIChub2RlIGluc3RhbmNlb2YgZG9jdW1lbnQuRG9jdW1lbnQpIHtcbiAgICAgIG5vZGUgPSBub2RlLmNvbnRlbnRba2V5XVxuICAgIH0gZWxzZSB7XG4gICAgICBub2RlID0gbm9kZVtrZXldXG4gICAgfVxuICAgIGlmIChub2RlID09PSB1bmRlZmluZWQpIHtcbiAgICAgIHRocm93IG5ldyBlcnJvcnMuTGlua0xvb2t1cEVycm9yKGBJbnZhbGlkIGxpbmsgbG9va3VwOiAke0pTT04uc3RyaW5naWZ5KGtleXMpfWApXG4gICAgfVxuICB9XG4gIGlmICghKG5vZGUgaW5zdGFuY2VvZiBkb2N1bWVudC5MaW5rKSkge1xuICAgIHRocm93IG5ldyBlcnJvcnMuTGlua0xvb2t1cEVycm9yKGBJbnZhbGlkIGxpbmsgbG9va3VwOiAke0pTT04uc3RyaW5naWZ5KGtleXMpfWApXG4gIH1cbiAgcmV0dXJuIG5vZGVcbn1cblxuY2xhc3MgQ2xpZW50IHtcbiAgY29uc3RydWN0b3IgKG9wdGlvbnMgPSB7fSkge1xuICAgIGNvbnN0IHRyYW5zcG9ydE9wdGlvbnMgPSB7XG4gICAgICBhdXRoOiBvcHRpb25zLmF1dGggfHwgbnVsbCxcbiAgICAgIGhlYWRlcnM6IG9wdGlvbnMuaGVhZGVycyB8fCB7fSxcbiAgICAgIHJlcXVlc3RDYWxsYmFjazogb3B0aW9ucy5yZXF1ZXN0Q2FsbGJhY2ssXG4gICAgICByZXNwb25zZUNhbGxiYWNrOiBvcHRpb25zLnJlc3BvbnNlQ2FsbGJhY2tcbiAgICB9XG5cbiAgICB0aGlzLmRlY29kZXJzID0gb3B0aW9ucy5kZWNvZGVycyB8fCBbbmV3IGNvZGVjcy5Db3JlSlNPTkNvZGVjKCksIG5ldyBjb2RlY3MuSlNPTkNvZGVjKCksIG5ldyBjb2RlY3MuVGV4dENvZGVjKCldXG4gICAgdGhpcy50cmFuc3BvcnRzID0gb3B0aW9ucy50cmFuc3BvcnRzIHx8IFtuZXcgdHJhbnNwb3J0cy5IVFRQVHJhbnNwb3J0KHRyYW5zcG9ydE9wdGlvbnMpXVxuICB9XG5cbiAgYWN0aW9uIChkb2N1bWVudCwga2V5cywgcGFyYW1zID0ge30pIHtcbiAgICBjb25zdCBsaW5rID0gbG9va3VwTGluayhkb2N1bWVudCwga2V5cylcbiAgICBjb25zdCB0cmFuc3BvcnQgPSB1dGlscy5kZXRlcm1pbmVUcmFuc3BvcnQodGhpcy50cmFuc3BvcnRzLCBsaW5rLnVybClcbiAgICByZXR1cm4gdHJhbnNwb3J0LmFjdGlvbihsaW5rLCB0aGlzLmRlY29kZXJzLCBwYXJhbXMpXG4gIH1cblxuICBnZXQgKHVybCkge1xuICAgIGNvbnN0IGxpbmsgPSBuZXcgZG9jdW1lbnQuTGluayh1cmwsICdnZXQnKVxuICAgIGNvbnN0IHRyYW5zcG9ydCA9IHV0aWxzLmRldGVybWluZVRyYW5zcG9ydCh0aGlzLnRyYW5zcG9ydHMsIHVybClcbiAgICByZXR1cm4gdHJhbnNwb3J0LmFjdGlvbihsaW5rLCB0aGlzLmRlY29kZXJzKVxuICB9XG59XG5cbm1vZHVsZS5leHBvcnRzID0ge1xuICBDbGllbnQ6IENsaWVudFxufVxuIiwiY29uc3QgZG9jdW1lbnQgPSByZXF1aXJlKCcuLi9kb2N1bWVudCcpXG5jb25zdCBVUkwgPSByZXF1aXJlKCd1cmwtcGFyc2UnKVxuXG5mdW5jdGlvbiB1bmVzY2FwZUtleSAoa2V5KSB7XG4gIGlmIChrZXkubWF0Y2goL19fKHR5cGV8bWV0YSkkLykpIHtcbiAgICByZXR1cm4ga2V5LnN1YnN0cmluZygxKVxuICB9XG4gIHJldHVybiBrZXlcbn1cblxuZnVuY3Rpb24gZ2V0U3RyaW5nIChvYmosIGtleSkge1xuICBjb25zdCB2YWx1ZSA9IG9ialtrZXldXG4gIGlmICh0eXBlb2YgKHZhbHVlKSA9PT0gJ3N0cmluZycpIHtcbiAgICByZXR1cm4gdmFsdWVcbiAgfVxuICByZXR1cm4gJydcbn1cblxuZnVuY3Rpb24gZ2V0Qm9vbGVhbiAob2JqLCBrZXkpIHtcbiAgY29uc3QgdmFsdWUgPSBvYmpba2V5XVxuICBpZiAodHlwZW9mICh2YWx1ZSkgPT09ICdib29sZWFuJykge1xuICAgIHJldHVybiB2YWx1ZVxuICB9XG4gIHJldHVybiBmYWxzZVxufVxuXG5mdW5jdGlvbiBnZXRPYmplY3QgKG9iaiwga2V5KSB7XG4gIGNvbnN0IHZhbHVlID0gb2JqW2tleV1cbiAgaWYgKHR5cGVvZiAodmFsdWUpID09PSAnb2JqZWN0Jykge1xuICAgIHJldHVybiB2YWx1ZVxuICB9XG4gIHJldHVybiB7fVxufVxuXG5mdW5jdGlvbiBnZXRBcnJheSAob2JqLCBrZXkpIHtcbiAgY29uc3QgdmFsdWUgPSBvYmpba2V5XVxuICBpZiAodmFsdWUgaW5zdGFuY2VvZiBBcnJheSkge1xuICAgIHJldHVybiB2YWx1ZVxuICB9XG4gIHJldHVybiBbXVxufVxuXG5mdW5jdGlvbiBnZXRDb250ZW50IChkYXRhLCBiYXNlVXJsKSB7XG4gIGNvbnN0IGV4Y2x1ZGVkID0gWydfdHlwZScsICdfbWV0YSddXG4gIHZhciBjb250ZW50ID0ge31cbiAgZm9yICh2YXIgcHJvcGVydHkgaW4gZGF0YSkge1xuICAgIGlmIChkYXRhLmhhc093blByb3BlcnR5KHByb3BlcnR5KSAmJiAhZXhjbHVkZWQuaW5jbHVkZXMocHJvcGVydHkpKSB7XG4gICAgICBjb25zdCBrZXkgPSB1bmVzY2FwZUtleShwcm9wZXJ0eSlcbiAgICAgIGNvbnN0IHZhbHVlID0gcHJpbWl0aXZlVG9Ob2RlKGRhdGFbcHJvcGVydHldLCBiYXNlVXJsKVxuICAgICAgY29udGVudFtrZXldID0gdmFsdWVcbiAgICB9XG4gIH1cbiAgcmV0dXJuIGNvbnRlbnRcbn1cblxuZnVuY3Rpb24gcHJpbWl0aXZlVG9Ob2RlIChkYXRhLCBiYXNlVXJsKSB7XG4gIGNvbnN0IGlzT2JqZWN0ID0gZGF0YSBpbnN0YW5jZW9mIE9iamVjdCAmJiAhKGRhdGEgaW5zdGFuY2VvZiBBcnJheSlcblxuICBpZiAoaXNPYmplY3QgJiYgZGF0YS5fdHlwZSA9PT0gJ2RvY3VtZW50Jykge1xuICAgIC8vIERvY3VtZW50XG4gICAgY29uc3QgbWV0YSA9IGdldE9iamVjdChkYXRhLCAnX21ldGEnKVxuICAgIGNvbnN0IHJlbGF0aXZlVXJsID0gZ2V0U3RyaW5nKG1ldGEsICd1cmwnKVxuICAgIGNvbnN0IHVybCA9IHJlbGF0aXZlVXJsID8gVVJMKHJlbGF0aXZlVXJsLCBiYXNlVXJsKS50b1N0cmluZygpIDogJydcbiAgICBjb25zdCB0aXRsZSA9IGdldFN0cmluZyhtZXRhLCAndGl0bGUnKVxuICAgIGNvbnN0IGRlc2NyaXB0aW9uID0gZ2V0U3RyaW5nKG1ldGEsICdkZXNjcmlwdGlvbicpXG4gICAgY29uc3QgY29udGVudCA9IGdldENvbnRlbnQoZGF0YSwgdXJsKVxuICAgIHJldHVybiBuZXcgZG9jdW1lbnQuRG9jdW1lbnQodXJsLCB0aXRsZSwgZGVzY3JpcHRpb24sIGNvbnRlbnQpXG4gIH0gZWxzZSBpZiAoaXNPYmplY3QgJiYgZGF0YS5fdHlwZSA9PT0gJ2xpbmsnKSB7XG4gICAgLy8gTGlua1xuICAgIGNvbnN0IHJlbGF0aXZlVXJsID0gZ2V0U3RyaW5nKGRhdGEsICd1cmwnKVxuICAgIGNvbnN0IHVybCA9IHJlbGF0aXZlVXJsID8gVVJMKHJlbGF0aXZlVXJsLCBiYXNlVXJsKS50b1N0cmluZygpIDogJydcbiAgICBjb25zdCBtZXRob2QgPSBnZXRTdHJpbmcoZGF0YSwgJ2FjdGlvbicpIHx8ICdnZXQnXG4gICAgY29uc3QgdGl0bGUgPSBnZXRTdHJpbmcoZGF0YSwgJ3RpdGxlJylcbiAgICBjb25zdCBkZXNjcmlwdGlvbiA9IGdldFN0cmluZyhkYXRhLCAnZGVzY3JpcHRpb24nKVxuICAgIGNvbnN0IGZpZWxkc0RhdGEgPSBnZXRBcnJheShkYXRhLCAnZmllbGRzJylcbiAgICB2YXIgZmllbGRzID0gW11cbiAgICBmb3IgKGxldCBpZHggPSAwLCBsZW4gPSBmaWVsZHNEYXRhLmxlbmd0aDsgaWR4IDwgbGVuOyBpZHgrKykge1xuICAgICAgbGV0IHZhbHVlID0gZmllbGRzRGF0YVtpZHhdXG4gICAgICBsZXQgbmFtZSA9IGdldFN0cmluZyh2YWx1ZSwgJ25hbWUnKVxuICAgICAgbGV0IHJlcXVpcmVkID0gZ2V0Qm9vbGVhbih2YWx1ZSwgJ3JlcXVpcmVkJylcbiAgICAgIGxldCBsb2NhdGlvbiA9IGdldFN0cmluZyh2YWx1ZSwgJ2xvY2F0aW9uJylcbiAgICAgIGxldCBmaWVsZERlc2NyaXB0aW9uID0gZ2V0U3RyaW5nKHZhbHVlLCAnZmllbGREZXNjcmlwdGlvbicpXG4gICAgICBsZXQgZmllbGQgPSBuZXcgZG9jdW1lbnQuRmllbGQobmFtZSwgcmVxdWlyZWQsIGxvY2F0aW9uLCBmaWVsZERlc2NyaXB0aW9uKVxuICAgICAgZmllbGRzLnB1c2goZmllbGQpXG4gICAgfVxuICAgIHJldHVybiBuZXcgZG9jdW1lbnQuTGluayh1cmwsIG1ldGhvZCwgJ2FwcGxpY2F0aW9uL2pzb24nLCBmaWVsZHMsIHRpdGxlLCBkZXNjcmlwdGlvbilcbiAgfSBlbHNlIGlmIChpc09iamVjdCkge1xuICAgIC8vIE9iamVjdFxuICAgIGxldCBjb250ZW50ID0ge31cbiAgICBmb3IgKGxldCBrZXkgaW4gZGF0YSkge1xuICAgICAgaWYgKGRhdGEuaGFzT3duUHJvcGVydHkoa2V5KSkge1xuICAgICAgICBjb250ZW50W2tleV0gPSBwcmltaXRpdmVUb05vZGUoZGF0YVtrZXldLCBiYXNlVXJsKVxuICAgICAgfVxuICAgIH1cbiAgICByZXR1cm4gY29udGVudFxuICB9IGVsc2UgaWYgKGRhdGEgaW5zdGFuY2VvZiBBcnJheSkge1xuICAgIC8vIE9iamVjdFxuICAgIGxldCBjb250ZW50ID0gW11cbiAgICBmb3IgKGxldCBpZHggPSAwLCBsZW4gPSBkYXRhLmxlbmd0aDsgaWR4IDwgbGVuOyBpZHgrKykge1xuICAgICAgY29udGVudC5wdXNoKHByaW1pdGl2ZVRvTm9kZShkYXRhW2lkeF0sIGJhc2VVcmwpKVxuICAgIH1cbiAgICByZXR1cm4gY29udGVudFxuICB9XG4gIC8vIFByaW1pdGl2ZVxuICByZXR1cm4gZGF0YVxufVxuXG5jbGFzcyBDb3JlSlNPTkNvZGVjIHtcbiAgY29uc3RydWN0b3IgKCkge1xuICAgIHRoaXMubWVkaWFUeXBlID0gJ2FwcGxpY2F0aW9uL2NvcmVhcGkranNvbidcbiAgfVxuXG4gIGRlY29kZSAodGV4dCwgb3B0aW9ucyA9IHt9KSB7XG4gICAgbGV0IGRhdGEgPSB0ZXh0XG4gICAgaWYgKG9wdGlvbnMucHJlbG9hZGVkID09PSB1bmRlZmluZWQgfHwgIW9wdGlvbnMucHJlbG9hZGVkKSB7XG4gICAgICBkYXRhID0gSlNPTi5wYXJzZSh0ZXh0KVxuICAgIH1cbiAgICByZXR1cm4gcHJpbWl0aXZlVG9Ob2RlKGRhdGEsIG9wdGlvbnMudXJsKVxuICB9XG59XG5cbm1vZHVsZS5leHBvcnRzID0ge1xuICBDb3JlSlNPTkNvZGVjOiBDb3JlSlNPTkNvZGVjXG59XG4iLCJjb25zdCBjb3JlanNvbiA9IHJlcXVpcmUoJy4vY29yZWpzb24nKVxuY29uc3QganNvbiA9IHJlcXVpcmUoJy4vanNvbicpXG5jb25zdCB0ZXh0ID0gcmVxdWlyZSgnLi90ZXh0JylcblxubW9kdWxlLmV4cG9ydHMgPSB7XG4gIENvcmVKU09OQ29kZWM6IGNvcmVqc29uLkNvcmVKU09OQ29kZWMsXG4gIEpTT05Db2RlYzoganNvbi5KU09OQ29kZWMsXG4gIFRleHRDb2RlYzogdGV4dC5UZXh0Q29kZWNcbn1cbiIsImNsYXNzIEpTT05Db2RlYyB7XG4gIGNvbnN0cnVjdG9yICgpIHtcbiAgICB0aGlzLm1lZGlhVHlwZSA9ICdhcHBsaWNhdGlvbi9qc29uJ1xuICB9XG5cbiAgZGVjb2RlICh0ZXh0LCBvcHRpb25zID0ge30pIHtcbiAgICByZXR1cm4gSlNPTi5wYXJzZSh0ZXh0KVxuICB9XG59XG5cbm1vZHVsZS5leHBvcnRzID0ge1xuICBKU09OQ29kZWM6IEpTT05Db2RlY1xufVxuIiwiY2xhc3MgVGV4dENvZGVjIHtcbiAgY29uc3RydWN0b3IgKCkge1xuICAgIHRoaXMubWVkaWFUeXBlID0gJ3RleHQvKidcbiAgfVxuXG4gIGRlY29kZSAodGV4dCwgb3B0aW9ucyA9IHt9KSB7XG4gICAgcmV0dXJuIHRleHRcbiAgfVxufVxuXG5tb2R1bGUuZXhwb3J0cyA9IHtcbiAgVGV4dENvZGVjOiBUZXh0Q29kZWNcbn1cbiIsImNsYXNzIERvY3VtZW50IHtcbiAgY29uc3RydWN0b3IgKHVybCA9ICcnLCB0aXRsZSA9ICcnLCBkZXNjcmlwdGlvbiA9ICcnLCBjb250ZW50ID0ge30pIHtcbiAgICB0aGlzLnVybCA9IHVybFxuICAgIHRoaXMudGl0bGUgPSB0aXRsZVxuICAgIHRoaXMuZGVzY3JpcHRpb24gPSBkZXNjcmlwdGlvblxuICAgIHRoaXMuY29udGVudCA9IGNvbnRlbnRcbiAgfVxufVxuXG5jbGFzcyBMaW5rIHtcbiAgY29uc3RydWN0b3IgKHVybCwgbWV0aG9kLCBlbmNvZGluZyA9ICdhcHBsaWNhdGlvbi9qc29uJywgZmllbGRzID0gW10sIHRpdGxlID0gJycsIGRlc2NyaXB0aW9uID0gJycpIHtcbiAgICBpZiAodXJsID09PSB1bmRlZmluZWQpIHtcbiAgICAgIHRocm93IG5ldyBFcnJvcigndXJsIGFyZ3VtZW50IGlzIHJlcXVpcmVkJylcbiAgICB9XG5cbiAgICBpZiAobWV0aG9kID09PSB1bmRlZmluZWQpIHtcbiAgICAgIHRocm93IG5ldyBFcnJvcignbWV0aG9kIGFyZ3VtZW50IGlzIHJlcXVpcmVkJylcbiAgICB9XG5cbiAgICB0aGlzLnVybCA9IHVybFxuICAgIHRoaXMubWV0aG9kID0gbWV0aG9kXG4gICAgdGhpcy5lbmNvZGluZyA9IGVuY29kaW5nXG4gICAgdGhpcy5maWVsZHMgPSBmaWVsZHNcbiAgICB0aGlzLnRpdGxlID0gdGl0bGVcbiAgICB0aGlzLmRlc2NyaXB0aW9uID0gZGVzY3JpcHRpb25cbiAgfVxufVxuXG5jbGFzcyBGaWVsZCB7XG4gIGNvbnN0cnVjdG9yIChuYW1lLCByZXF1aXJlZCA9IGZhbHNlLCBsb2NhdGlvbiA9ICcnLCBkZXNjcmlwdGlvbiA9ICcnKSB7XG4gICAgaWYgKG5hbWUgPT09IHVuZGVmaW5lZCkge1xuICAgICAgdGhyb3cgbmV3IEVycm9yKCduYW1lIGFyZ3VtZW50IGlzIHJlcXVpcmVkJylcbiAgICB9XG5cbiAgICB0aGlzLm5hbWUgPSBuYW1lXG4gICAgdGhpcy5yZXF1aXJlZCA9IHJlcXVpcmVkXG4gICAgdGhpcy5sb2NhdGlvbiA9IGxvY2F0aW9uXG4gICAgdGhpcy5kZXNjcmlwdGlvbiA9IGRlc2NyaXB0aW9uXG4gIH1cbn1cblxubW9kdWxlLmV4cG9ydHMgPSB7XG4gIERvY3VtZW50OiBEb2N1bWVudCxcbiAgTGluazogTGluayxcbiAgRmllbGQ6IEZpZWxkXG59XG4iLCJjbGFzcyBQYXJhbWV0ZXJFcnJvciBleHRlbmRzIEVycm9yIHtcbiAgY29uc3RydWN0b3IgKG1lc3NhZ2UpIHtcbiAgICBzdXBlcihtZXNzYWdlKVxuICAgIHRoaXMubWVzc2FnZSA9IG1lc3NhZ2VcbiAgICB0aGlzLm5hbWUgPSAnUGFyYW1ldGVyRXJyb3InXG4gIH1cbn1cblxuY2xhc3MgTGlua0xvb2t1cEVycm9yIGV4dGVuZHMgRXJyb3Ige1xuICBjb25zdHJ1Y3RvciAobWVzc2FnZSkge1xuICAgIHN1cGVyKG1lc3NhZ2UpXG4gICAgdGhpcy5tZXNzYWdlID0gbWVzc2FnZVxuICAgIHRoaXMubmFtZSA9ICdMaW5rTG9va3VwRXJyb3InXG4gIH1cbn1cblxuY2xhc3MgRXJyb3JNZXNzYWdlIGV4dGVuZHMgRXJyb3Ige1xuICBjb25zdHJ1Y3RvciAobWVzc2FnZSwgY29udGVudCkge1xuICAgIHN1cGVyKG1lc3NhZ2UpXG4gICAgdGhpcy5tZXNzYWdlID0gbWVzc2FnZVxuICAgIHRoaXMuY29udGVudCA9IGNvbnRlbnRcbiAgICB0aGlzLm5hbWUgPSAnRXJyb3JNZXNzYWdlJ1xuICB9XG59XG5cbm1vZHVsZS5leHBvcnRzID0ge1xuICBQYXJhbWV0ZXJFcnJvcjogUGFyYW1ldGVyRXJyb3IsXG4gIExpbmtMb29rdXBFcnJvcjogTGlua0xvb2t1cEVycm9yLFxuICBFcnJvck1lc3NhZ2U6IEVycm9yTWVzc2FnZVxufVxuIiwiY29uc3QgYXV0aCA9IHJlcXVpcmUoJy4vYXV0aCcpXG5jb25zdCBjbGllbnQgPSByZXF1aXJlKCcuL2NsaWVudCcpXG5jb25zdCBjb2RlY3MgPSByZXF1aXJlKCcuL2NvZGVjcycpXG5jb25zdCBkb2N1bWVudCA9IHJlcXVpcmUoJy4vZG9jdW1lbnQnKVxuY29uc3QgZXJyb3JzID0gcmVxdWlyZSgnLi9lcnJvcnMnKVxuY29uc3QgdHJhbnNwb3J0cyA9IHJlcXVpcmUoJy4vdHJhbnNwb3J0cycpXG5jb25zdCB1dGlscyA9IHJlcXVpcmUoJy4vdXRpbHMnKVxuXG5jb25zdCBjb3JlYXBpID0ge1xuICBDbGllbnQ6IGNsaWVudC5DbGllbnQsXG4gIERvY3VtZW50OiBkb2N1bWVudC5Eb2N1bWVudCxcbiAgTGluazogZG9jdW1lbnQuTGluayxcbiAgYXV0aDogYXV0aCxcbiAgY29kZWNzOiBjb2RlY3MsXG4gIGVycm9yczogZXJyb3JzLFxuICB0cmFuc3BvcnRzOiB0cmFuc3BvcnRzLFxuICB1dGlsczogdXRpbHNcbn1cblxubW9kdWxlLmV4cG9ydHMgPSBjb3JlYXBpXG4iLCJjb25zdCBmZXRjaCA9IHJlcXVpcmUoJ2lzb21vcnBoaWMtZmV0Y2gnKVxuY29uc3QgZXJyb3JzID0gcmVxdWlyZSgnLi4vZXJyb3JzJylcbmNvbnN0IHV0aWxzID0gcmVxdWlyZSgnLi4vdXRpbHMnKVxuY29uc3QgVVJMID0gcmVxdWlyZSgndXJsLXBhcnNlJylcbmNvbnN0IHVybFRlbXBsYXRlID0gcmVxdWlyZSgndXJsLXRlbXBsYXRlJylcblxuY29uc3QgcGFyc2VSZXNwb25zZSA9IChyZXNwb25zZSwgZGVjb2RlcnMsIHJlc3BvbnNlQ2FsbGJhY2spID0+IHtcbiAgcmV0dXJuIHJlc3BvbnNlLnRleHQoKS50aGVuKHRleHQgPT4ge1xuICAgIGlmIChyZXNwb25zZUNhbGxiYWNrKSB7XG4gICAgICByZXNwb25zZUNhbGxiYWNrKHJlc3BvbnNlLCB0ZXh0KVxuICAgIH1cbiAgICBjb25zdCBjb250ZW50VHlwZSA9IHJlc3BvbnNlLmhlYWRlcnMuZ2V0KCdDb250ZW50LVR5cGUnKVxuICAgIGNvbnN0IGRlY29kZXIgPSB1dGlscy5uZWdvdGlhdGVEZWNvZGVyKGRlY29kZXJzLCBjb250ZW50VHlwZSlcbiAgICBjb25zdCBvcHRpb25zID0ge3VybDogcmVzcG9uc2UudXJsfVxuICAgIHJldHVybiBkZWNvZGVyLmRlY29kZSh0ZXh0LCBvcHRpb25zKVxuICB9KVxufVxuXG5jbGFzcyBIVFRQVHJhbnNwb3J0IHtcbiAgY29uc3RydWN0b3IgKG9wdGlvbnMgPSB7fSkge1xuICAgIHRoaXMuc2NoZW1lcyA9IFsnaHR0cCcsICdodHRwcyddXG4gICAgdGhpcy5hdXRoID0gb3B0aW9ucy5hdXRoIHx8IG51bGxcbiAgICB0aGlzLmhlYWRlcnMgPSBvcHRpb25zLmhlYWRlcnMgfHwge31cbiAgICB0aGlzLmZldGNoID0gb3B0aW9ucy5mZXRjaCB8fCBmZXRjaFxuICAgIHRoaXMuRm9ybURhdGEgPSBvcHRpb25zLkZvcm1EYXRhIHx8IHdpbmRvdy5Gb3JtRGF0YVxuICAgIHRoaXMucmVxdWVzdENhbGxiYWNrID0gb3B0aW9ucy5yZXF1ZXN0Q2FsbGJhY2tcbiAgICB0aGlzLnJlc3BvbnNlQ2FsbGJhY2sgPSBvcHRpb25zLnJlc3BvbnNlQ2FsbGJhY2tcbiAgfVxuXG4gIGJ1aWxkUmVxdWVzdCAobGluaywgZGVjb2RlcnMsIHBhcmFtcyA9IHt9KSB7XG4gICAgY29uc3QgZmllbGRzID0gbGluay5maWVsZHNcbiAgICBjb25zdCBtZXRob2QgPSBsaW5rLm1ldGhvZC50b1VwcGVyQ2FzZSgpXG4gICAgbGV0IHF1ZXJ5UGFyYW1zID0ge31cbiAgICBsZXQgcGF0aFBhcmFtcyA9IHt9XG4gICAgbGV0IGZvcm1QYXJhbXMgPSB7fVxuICAgIGxldCBmaWVsZE5hbWVzID0gW11cbiAgICBsZXQgaGFzQm9keSA9IGZhbHNlXG5cbiAgICBmb3IgKGxldCBpZHggPSAwLCBsZW4gPSBmaWVsZHMubGVuZ3RoOyBpZHggPCBsZW47IGlkeCsrKSB7XG4gICAgICBjb25zdCBmaWVsZCA9IGZpZWxkc1tpZHhdXG5cbiAgICAgIC8vIEVuc3VyZSBhbnkgcmVxdWlyZWQgZmllbGRzIGFyZSBpbmNsdWRlZFxuICAgICAgaWYgKCFwYXJhbXMuaGFzT3duUHJvcGVydHkoZmllbGQubmFtZSkpIHtcbiAgICAgICAgaWYgKGZpZWxkLnJlcXVpcmVkKSB7XG4gICAgICAgICAgdGhyb3cgbmV3IGVycm9ycy5QYXJhbWV0ZXJFcnJvcihgTWlzc2luZyByZXF1aXJlZCBmaWVsZDogXCIke2ZpZWxkLm5hbWV9XCJgKVxuICAgICAgICB9IGVsc2Uge1xuICAgICAgICAgIGNvbnRpbnVlXG4gICAgICAgIH1cbiAgICAgIH1cblxuICAgICAgZmllbGROYW1lcy5wdXNoKGZpZWxkLm5hbWUpXG4gICAgICBpZiAoZmllbGQubG9jYXRpb24gPT09ICdxdWVyeScpIHtcbiAgICAgICAgcXVlcnlQYXJhbXNbZmllbGQubmFtZV0gPSBwYXJhbXNbZmllbGQubmFtZV1cbiAgICAgIH0gZWxzZSBpZiAoZmllbGQubG9jYXRpb24gPT09ICdwYXRoJykge1xuICAgICAgICBwYXRoUGFyYW1zW2ZpZWxkLm5hbWVdID0gcGFyYW1zW2ZpZWxkLm5hbWVdXG4gICAgICB9IGVsc2UgaWYgKGZpZWxkLmxvY2F0aW9uID09PSAnZm9ybScpIHtcbiAgICAgICAgZm9ybVBhcmFtc1tmaWVsZC5uYW1lXSA9IHBhcmFtc1tmaWVsZC5uYW1lXVxuICAgICAgICBoYXNCb2R5ID0gdHJ1ZVxuICAgICAgfSBlbHNlIGlmIChmaWVsZC5sb2NhdGlvbiA9PT0gJ2JvZHknKSB7XG4gICAgICAgIGZvcm1QYXJhbXMgPSBwYXJhbXNbZmllbGQubmFtZV1cbiAgICAgICAgaGFzQm9keSA9IHRydWVcbiAgICAgIH1cbiAgICB9XG5cbiAgICAvLyBDaGVjayBmb3IgYW55IHBhcmFtZXRlcnMgdGhhdCBkaWQgbm90IGhhdmUgYSBtYXRjaGluZyBmaWVsZFxuICAgIGZvciAodmFyIHByb3BlcnR5IGluIHBhcmFtcykge1xuICAgICAgaWYgKHBhcmFtcy5oYXNPd25Qcm9wZXJ0eShwcm9wZXJ0eSkgJiYgIWZpZWxkTmFtZXMuaW5jbHVkZXMocHJvcGVydHkpKSB7XG4gICAgICAgIHRocm93IG5ldyBlcnJvcnMuUGFyYW1ldGVyRXJyb3IoYFVua25vd24gcGFyYW1ldGVyOiBcIiR7cHJvcGVydHl9XCJgKVxuICAgICAgfVxuICAgIH1cblxuICAgIGxldCByZXF1ZXN0T3B0aW9ucyA9IHttZXRob2Q6IG1ldGhvZCwgaGVhZGVyczoge319XG5cbiAgICBPYmplY3QuYXNzaWduKHJlcXVlc3RPcHRpb25zLmhlYWRlcnMsIHRoaXMuaGVhZGVycylcblxuICAgIGlmIChoYXNCb2R5KSB7XG4gICAgICBpZiAobGluay5lbmNvZGluZyA9PT0gJ2FwcGxpY2F0aW9uL2pzb24nKSB7XG4gICAgICAgIHJlcXVlc3RPcHRpb25zLmJvZHkgPSBKU09OLnN0cmluZ2lmeShmb3JtUGFyYW1zKVxuICAgICAgICByZXF1ZXN0T3B0aW9ucy5oZWFkZXJzWydDb250ZW50LVR5cGUnXSA9ICdhcHBsaWNhdGlvbi9qc29uJ1xuICAgICAgfSBlbHNlIGlmIChsaW5rLmVuY29kaW5nID09PSAnbXVsdGlwYXJ0L2Zvcm0tZGF0YScpIHtcbiAgICAgICAgbGV0IGZvcm0gPSBuZXcgdGhpcy5Gb3JtRGF0YSgpXG5cbiAgICAgICAgZm9yIChsZXQgcGFyYW1LZXkgaW4gZm9ybVBhcmFtcykge1xuICAgICAgICAgIGZvcm0uYXBwZW5kKHBhcmFtS2V5LCBmb3JtUGFyYW1zW3BhcmFtS2V5XSlcbiAgICAgICAgfVxuICAgICAgICByZXF1ZXN0T3B0aW9ucy5ib2R5ID0gZm9ybVxuICAgICAgfSBlbHNlIGlmIChsaW5rLmVuY29kaW5nID09PSAnYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkJykge1xuICAgICAgICBsZXQgZm9ybUJvZHkgPSBbXVxuICAgICAgICBmb3IgKGxldCBwYXJhbUtleSBpbiBmb3JtUGFyYW1zKSB7XG4gICAgICAgICAgY29uc3QgZW5jb2RlZEtleSA9IGVuY29kZVVSSUNvbXBvbmVudChwYXJhbUtleSlcbiAgICAgICAgICBjb25zdCBlbmNvZGVkVmFsdWUgPSBlbmNvZGVVUklDb21wb25lbnQoZm9ybVBhcmFtc1twYXJhbUtleV0pXG4gICAgICAgICAgZm9ybUJvZHkucHVzaChlbmNvZGVkS2V5ICsgJz0nICsgZW5jb2RlZFZhbHVlKVxuICAgICAgICB9XG4gICAgICAgIGZvcm1Cb2R5ID0gZm9ybUJvZHkuam9pbignJicpXG5cbiAgICAgICAgcmVxdWVzdE9wdGlvbnMuYm9keSA9IGZvcm1Cb2R5XG4gICAgICAgIHJlcXVlc3RPcHRpb25zLmhlYWRlcnNbJ0NvbnRlbnQtVHlwZSddID0gJ2FwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCdcbiAgICAgIH1cbiAgICB9XG5cbiAgICBpZiAodGhpcy5hdXRoKSB7XG4gICAgICByZXF1ZXN0T3B0aW9ucyA9IHRoaXMuYXV0aC5hdXRoZW50aWNhdGUocmVxdWVzdE9wdGlvbnMpXG4gICAgfVxuXG4gICAgbGV0IHBhcnNlZFVybCA9IHVybFRlbXBsYXRlLnBhcnNlKGxpbmsudXJsKVxuICAgIHBhcnNlZFVybCA9IHBhcnNlZFVybC5leHBhbmQocGF0aFBhcmFtcylcbiAgICBwYXJzZWRVcmwgPSBuZXcgVVJMKHBhcnNlZFVybClcbiAgICBwYXJzZWRVcmwuc2V0KCdxdWVyeScsIHF1ZXJ5UGFyYW1zKVxuXG4gICAgcmV0dXJuIHtcbiAgICAgIHVybDogcGFyc2VkVXJsLnRvU3RyaW5nKCksXG4gICAgICBvcHRpb25zOiByZXF1ZXN0T3B0aW9uc1xuICAgIH1cbiAgfVxuXG4gIGFjdGlvbiAobGluaywgZGVjb2RlcnMsIHBhcmFtcyA9IHt9KSB7XG4gICAgY29uc3QgcmVzcG9uc2VDYWxsYmFjayA9IHRoaXMucmVzcG9uc2VDYWxsYmFja1xuICAgIGNvbnN0IHJlcXVlc3QgPSB0aGlzLmJ1aWxkUmVxdWVzdChsaW5rLCBkZWNvZGVycywgcGFyYW1zKVxuXG4gICAgaWYgKHRoaXMucmVxdWVzdENhbGxiYWNrKSB7XG4gICAgICB0aGlzLnJlcXVlc3RDYWxsYmFjayhyZXF1ZXN0KVxuICAgIH1cblxuICAgIHJldHVybiB0aGlzLmZldGNoKHJlcXVlc3QudXJsLCByZXF1ZXN0Lm9wdGlvbnMpXG4gICAgICAudGhlbihmdW5jdGlvbiAocmVzcG9uc2UpIHtcbiAgICAgICAgaWYgKHJlc3BvbnNlLnN0YXR1cyA9PT0gMjA0KSB7XG4gICAgICAgICAgcmV0dXJuXG4gICAgICAgIH1cbiAgICAgICAgcmV0dXJuIHBhcnNlUmVzcG9uc2UocmVzcG9uc2UsIGRlY29kZXJzLCByZXNwb25zZUNhbGxiYWNrKVxuICAgICAgICAgIC50aGVuKGZ1bmN0aW9uIChkYXRhKSB7XG4gICAgICAgICAgICBpZiAocmVzcG9uc2Uub2spIHtcbiAgICAgICAgICAgICAgcmV0dXJuIGRhdGFcbiAgICAgICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgICAgIGNvbnN0IHRpdGxlID0gcmVzcG9uc2Uuc3RhdHVzICsgJyAnICsgcmVzcG9uc2Uuc3RhdHVzVGV4dFxuICAgICAgICAgICAgICBjb25zdCBlcnJvciA9IG5ldyBlcnJvcnMuRXJyb3JNZXNzYWdlKHRpdGxlLCBkYXRhKVxuICAgICAgICAgICAgICByZXR1cm4gUHJvbWlzZS5yZWplY3QoZXJyb3IpXG4gICAgICAgICAgICB9XG4gICAgICAgICAgfSlcbiAgICAgIH0pXG4gIH1cbn1cblxubW9kdWxlLmV4cG9ydHMgPSB7XG4gIEhUVFBUcmFuc3BvcnQ6IEhUVFBUcmFuc3BvcnRcbn1cbiIsImNvbnN0IGh0dHAgPSByZXF1aXJlKCcuL2h0dHAnKVxuXG5tb2R1bGUuZXhwb3J0cyA9IHtcbiAgSFRUUFRyYW5zcG9ydDogaHR0cC5IVFRQVHJhbnNwb3J0XG59XG4iLCJjb25zdCBVUkwgPSByZXF1aXJlKCd1cmwtcGFyc2UnKVxuXG5jb25zdCBkZXRlcm1pbmVUcmFuc3BvcnQgPSBmdW5jdGlvbiAodHJhbnNwb3J0cywgdXJsKSB7XG4gIGNvbnN0IHBhcnNlZFVybCA9IG5ldyBVUkwodXJsKVxuICBjb25zdCBzY2hlbWUgPSBwYXJzZWRVcmwucHJvdG9jb2wucmVwbGFjZSgnOicsICcnKVxuXG4gIGZvciAobGV0IHRyYW5zcG9ydCBvZiB0cmFuc3BvcnRzKSB7XG4gICAgaWYgKHRyYW5zcG9ydC5zY2hlbWVzLmluY2x1ZGVzKHNjaGVtZSkpIHtcbiAgICAgIHJldHVybiB0cmFuc3BvcnRcbiAgICB9XG4gIH1cblxuICB0aHJvdyBFcnJvcihgVW5zdXBwb3J0ZWQgc2NoZW1lIGluIFVSTDogJHt1cmx9YClcbn1cblxuY29uc3QgbmVnb3RpYXRlRGVjb2RlciA9IGZ1bmN0aW9uIChkZWNvZGVycywgY29udGVudFR5cGUpIHtcbiAgaWYgKGNvbnRlbnRUeXBlID09PSB1bmRlZmluZWQgfHwgY29udGVudFR5cGUgPT09IG51bGwpIHtcbiAgICByZXR1cm4gZGVjb2RlcnNbMF1cbiAgfVxuXG4gIGNvbnN0IGZ1bGxUeXBlID0gY29udGVudFR5cGUudG9Mb3dlckNhc2UoKS5zcGxpdCgnOycpWzBdLnRyaW0oKVxuICBjb25zdCBtYWluVHlwZSA9IGZ1bGxUeXBlLnNwbGl0KCcvJylbMF0gKyAnLyonXG4gIGNvbnN0IHdpbGRjYXJkVHlwZSA9ICcqLyonXG4gIGNvbnN0IGFjY2VwdGFibGVUeXBlcyA9IFtmdWxsVHlwZSwgbWFpblR5cGUsIHdpbGRjYXJkVHlwZV1cblxuICBmb3IgKGxldCBkZWNvZGVyIG9mIGRlY29kZXJzKSB7XG4gICAgaWYgKGFjY2VwdGFibGVUeXBlcy5pbmNsdWRlcyhkZWNvZGVyLm1lZGlhVHlwZSkpIHtcbiAgICAgIHJldHVybiBkZWNvZGVyXG4gICAgfVxuICB9XG5cbiAgdGhyb3cgRXJyb3IoYFVuc3VwcG9ydGVkIG1lZGlhIGluIENvbnRlbnQtVHlwZSBoZWFkZXI6ICR7Y29udGVudFR5cGV9YClcbn1cblxuY29uc3QgY3NyZlNhZmVNZXRob2QgPSBmdW5jdGlvbiAobWV0aG9kKSB7XG4gIC8vIHRoZXNlIEhUVFAgbWV0aG9kcyBkbyBub3QgcmVxdWlyZSBDU1JGIHByb3RlY3Rpb25cbiAgcmV0dXJuICgvXihHRVR8SEVBRHxPUFRJT05TfFRSQUNFKSQvLnRlc3QobWV0aG9kKSlcbn1cblxubW9kdWxlLmV4cG9ydHMgPSB7XG4gIGRldGVybWluZVRyYW5zcG9ydDogZGV0ZXJtaW5lVHJhbnNwb3J0LFxuICBuZWdvdGlhdGVEZWNvZGVyOiBuZWdvdGlhdGVEZWNvZGVyLFxuICBjc3JmU2FmZU1ldGhvZDogY3NyZlNhZmVNZXRob2Rcbn1cbiIsIi8vIHRoZSB3aGF0d2ctZmV0Y2ggcG9seWZpbGwgaW5zdGFsbHMgdGhlIGZldGNoKCkgZnVuY3Rpb25cbi8vIG9uIHRoZSBnbG9iYWwgb2JqZWN0ICh3aW5kb3cgb3Igc2VsZilcbi8vXG4vLyBSZXR1cm4gdGhhdCBhcyB0aGUgZXhwb3J0IGZvciB1c2UgaW4gV2VicGFjaywgQnJvd3NlcmlmeSBldGMuXG5yZXF1aXJlKCd3aGF0d2ctZmV0Y2gnKTtcbm1vZHVsZS5leHBvcnRzID0gc2VsZi5mZXRjaC5iaW5kKHNlbGYpO1xuIiwiJ3VzZSBzdHJpY3QnO1xuXG52YXIgaGFzID0gT2JqZWN0LnByb3RvdHlwZS5oYXNPd25Qcm9wZXJ0eTtcblxuLyoqXG4gKiBTaW1wbGUgcXVlcnkgc3RyaW5nIHBhcnNlci5cbiAqXG4gKiBAcGFyYW0ge1N0cmluZ30gcXVlcnkgVGhlIHF1ZXJ5IHN0cmluZyB0aGF0IG5lZWRzIHRvIGJlIHBhcnNlZC5cbiAqIEByZXR1cm5zIHtPYmplY3R9XG4gKiBAYXBpIHB1YmxpY1xuICovXG5mdW5jdGlvbiBxdWVyeXN0cmluZyhxdWVyeSkge1xuICB2YXIgcGFyc2VyID0gLyhbXj0/Jl0rKT0/KFteJl0qKS9nXG4gICAgLCByZXN1bHQgPSB7fVxuICAgICwgcGFydDtcblxuICAvL1xuICAvLyBMaXR0bGUgbmlmdHkgcGFyc2luZyBoYWNrLCBsZXZlcmFnZSB0aGUgZmFjdCB0aGF0IFJlZ0V4cC5leGVjIGluY3JlbWVudHNcbiAgLy8gdGhlIGxhc3RJbmRleCBwcm9wZXJ0eSBzbyB3ZSBjYW4gY29udGludWUgZXhlY3V0aW5nIHRoaXMgbG9vcCB1bnRpbCB3ZSd2ZVxuICAvLyBwYXJzZWQgYWxsIHJlc3VsdHMuXG4gIC8vXG4gIGZvciAoO1xuICAgIHBhcnQgPSBwYXJzZXIuZXhlYyhxdWVyeSk7XG4gICAgcmVzdWx0W2RlY29kZVVSSUNvbXBvbmVudChwYXJ0WzFdKV0gPSBkZWNvZGVVUklDb21wb25lbnQocGFydFsyXSlcbiAgKTtcblxuICByZXR1cm4gcmVzdWx0O1xufVxuXG4vKipcbiAqIFRyYW5zZm9ybSBhIHF1ZXJ5IHN0cmluZyB0byBhbiBvYmplY3QuXG4gKlxuICogQHBhcmFtIHtPYmplY3R9IG9iaiBPYmplY3QgdGhhdCBzaG91bGQgYmUgdHJhbnNmb3JtZWQuXG4gKiBAcGFyYW0ge1N0cmluZ30gcHJlZml4IE9wdGlvbmFsIHByZWZpeC5cbiAqIEByZXR1cm5zIHtTdHJpbmd9XG4gKiBAYXBpIHB1YmxpY1xuICovXG5mdW5jdGlvbiBxdWVyeXN0cmluZ2lmeShvYmosIHByZWZpeCkge1xuICBwcmVmaXggPSBwcmVmaXggfHwgJyc7XG5cbiAgdmFyIHBhaXJzID0gW107XG5cbiAgLy9cbiAgLy8gT3B0aW9uYWxseSBwcmVmaXggd2l0aCBhICc/JyBpZiBuZWVkZWRcbiAgLy9cbiAgaWYgKCdzdHJpbmcnICE9PSB0eXBlb2YgcHJlZml4KSBwcmVmaXggPSAnPyc7XG5cbiAgZm9yICh2YXIga2V5IGluIG9iaikge1xuICAgIGlmIChoYXMuY2FsbChvYmosIGtleSkpIHtcbiAgICAgIHBhaXJzLnB1c2goZW5jb2RlVVJJQ29tcG9uZW50KGtleSkgKyc9JysgZW5jb2RlVVJJQ29tcG9uZW50KG9ialtrZXldKSk7XG4gICAgfVxuICB9XG5cbiAgcmV0dXJuIHBhaXJzLmxlbmd0aCA/IHByZWZpeCArIHBhaXJzLmpvaW4oJyYnKSA6ICcnO1xufVxuXG4vL1xuLy8gRXhwb3NlIHRoZSBtb2R1bGUuXG4vL1xuZXhwb3J0cy5zdHJpbmdpZnkgPSBxdWVyeXN0cmluZ2lmeTtcbmV4cG9ydHMucGFyc2UgPSBxdWVyeXN0cmluZztcbiIsIid1c2Ugc3RyaWN0JztcblxuLyoqXG4gKiBDaGVjayBpZiB3ZSdyZSByZXF1aXJlZCB0byBhZGQgYSBwb3J0IG51bWJlci5cbiAqXG4gKiBAc2VlIGh0dHBzOi8vdXJsLnNwZWMud2hhdHdnLm9yZy8jZGVmYXVsdC1wb3J0XG4gKiBAcGFyYW0ge051bWJlcnxTdHJpbmd9IHBvcnQgUG9ydCBudW1iZXIgd2UgbmVlZCB0byBjaGVja1xuICogQHBhcmFtIHtTdHJpbmd9IHByb3RvY29sIFByb3RvY29sIHdlIG5lZWQgdG8gY2hlY2sgYWdhaW5zdC5cbiAqIEByZXR1cm5zIHtCb29sZWFufSBJcyBpdCBhIGRlZmF1bHQgcG9ydCBmb3IgdGhlIGdpdmVuIHByb3RvY29sXG4gKiBAYXBpIHByaXZhdGVcbiAqL1xubW9kdWxlLmV4cG9ydHMgPSBmdW5jdGlvbiByZXF1aXJlZChwb3J0LCBwcm90b2NvbCkge1xuICBwcm90b2NvbCA9IHByb3RvY29sLnNwbGl0KCc6JylbMF07XG4gIHBvcnQgPSArcG9ydDtcblxuICBpZiAoIXBvcnQpIHJldHVybiBmYWxzZTtcblxuICBzd2l0Y2ggKHByb3RvY29sKSB7XG4gICAgY2FzZSAnaHR0cCc6XG4gICAgY2FzZSAnd3MnOlxuICAgIHJldHVybiBwb3J0ICE9PSA4MDtcblxuICAgIGNhc2UgJ2h0dHBzJzpcbiAgICBjYXNlICd3c3MnOlxuICAgIHJldHVybiBwb3J0ICE9PSA0NDM7XG5cbiAgICBjYXNlICdmdHAnOlxuICAgIHJldHVybiBwb3J0ICE9PSAyMTtcblxuICAgIGNhc2UgJ2dvcGhlcic6XG4gICAgcmV0dXJuIHBvcnQgIT09IDcwO1xuXG4gICAgY2FzZSAnZmlsZSc6XG4gICAgcmV0dXJuIGZhbHNlO1xuICB9XG5cbiAgcmV0dXJuIHBvcnQgIT09IDA7XG59O1xuIiwiJ3VzZSBzdHJpY3QnO1xuXG52YXIgcmVxdWlyZWQgPSByZXF1aXJlKCdyZXF1aXJlcy1wb3J0JylcbiAgLCBsb2xjYXRpb24gPSByZXF1aXJlKCcuL2xvbGNhdGlvbicpXG4gICwgcXMgPSByZXF1aXJlKCdxdWVyeXN0cmluZ2lmeScpXG4gICwgcHJvdG9jb2xyZSA9IC9eKFthLXpdW2EtejAtOS4rLV0qOik/KFxcL1xcLyk/KFtcXFNcXHNdKikvaTtcblxuLyoqXG4gKiBUaGVzZSBhcmUgdGhlIHBhcnNlIHJ1bGVzIGZvciB0aGUgVVJMIHBhcnNlciwgaXQgaW5mb3JtcyB0aGUgcGFyc2VyXG4gKiBhYm91dDpcbiAqXG4gKiAwLiBUaGUgY2hhciBpdCBOZWVkcyB0byBwYXJzZSwgaWYgaXQncyBhIHN0cmluZyBpdCBzaG91bGQgYmUgZG9uZSB1c2luZ1xuICogICAgaW5kZXhPZiwgUmVnRXhwIHVzaW5nIGV4ZWMgYW5kIE5hTiBtZWFucyBzZXQgYXMgY3VycmVudCB2YWx1ZS5cbiAqIDEuIFRoZSBwcm9wZXJ0eSB3ZSBzaG91bGQgc2V0IHdoZW4gcGFyc2luZyB0aGlzIHZhbHVlLlxuICogMi4gSW5kaWNhdGlvbiBpZiBpdCdzIGJhY2t3YXJkcyBvciBmb3J3YXJkIHBhcnNpbmcsIHdoZW4gc2V0IGFzIG51bWJlciBpdCdzXG4gKiAgICB0aGUgdmFsdWUgb2YgZXh0cmEgY2hhcnMgdGhhdCBzaG91bGQgYmUgc3BsaXQgb2ZmLlxuICogMy4gSW5oZXJpdCBmcm9tIGxvY2F0aW9uIGlmIG5vbiBleGlzdGluZyBpbiB0aGUgcGFyc2VyLlxuICogNC4gYHRvTG93ZXJDYXNlYCB0aGUgcmVzdWx0aW5nIHZhbHVlLlxuICovXG52YXIgcnVsZXMgPSBbXG4gIFsnIycsICdoYXNoJ10sICAgICAgICAgICAgICAgICAgICAgICAgLy8gRXh0cmFjdCBmcm9tIHRoZSBiYWNrLlxuICBbJz8nLCAncXVlcnknXSwgICAgICAgICAgICAgICAgICAgICAgIC8vIEV4dHJhY3QgZnJvbSB0aGUgYmFjay5cbiAgWycvJywgJ3BhdGhuYW1lJ10sICAgICAgICAgICAgICAgICAgICAvLyBFeHRyYWN0IGZyb20gdGhlIGJhY2suXG4gIFsnQCcsICdhdXRoJywgMV0sICAgICAgICAgICAgICAgICAgICAgLy8gRXh0cmFjdCBmcm9tIHRoZSBmcm9udC5cbiAgW05hTiwgJ2hvc3QnLCB1bmRlZmluZWQsIDEsIDFdLCAgICAgICAvLyBTZXQgbGVmdCBvdmVyIHZhbHVlLlxuICBbLzooXFxkKykkLywgJ3BvcnQnLCB1bmRlZmluZWQsIDFdLCAgICAvLyBSZWdFeHAgdGhlIGJhY2suXG4gIFtOYU4sICdob3N0bmFtZScsIHVuZGVmaW5lZCwgMSwgMV0gICAgLy8gU2V0IGxlZnQgb3Zlci5cbl07XG5cbi8qKlxuICogQHR5cGVkZWYgUHJvdG9jb2xFeHRyYWN0XG4gKiBAdHlwZSBPYmplY3RcbiAqIEBwcm9wZXJ0eSB7U3RyaW5nfSBwcm90b2NvbCBQcm90b2NvbCBtYXRjaGVkIGluIHRoZSBVUkwsIGluIGxvd2VyY2FzZS5cbiAqIEBwcm9wZXJ0eSB7Qm9vbGVhbn0gc2xhc2hlcyBgdHJ1ZWAgaWYgcHJvdG9jb2wgaXMgZm9sbG93ZWQgYnkgXCIvL1wiLCBlbHNlIGBmYWxzZWAuXG4gKiBAcHJvcGVydHkge1N0cmluZ30gcmVzdCBSZXN0IG9mIHRoZSBVUkwgdGhhdCBpcyBub3QgcGFydCBvZiB0aGUgcHJvdG9jb2wuXG4gKi9cblxuLyoqXG4gKiBFeHRyYWN0IHByb3RvY29sIGluZm9ybWF0aW9uIGZyb20gYSBVUkwgd2l0aC93aXRob3V0IGRvdWJsZSBzbGFzaCAoXCIvL1wiKS5cbiAqXG4gKiBAcGFyYW0ge1N0cmluZ30gYWRkcmVzcyBVUkwgd2Ugd2FudCB0byBleHRyYWN0IGZyb20uXG4gKiBAcmV0dXJuIHtQcm90b2NvbEV4dHJhY3R9IEV4dHJhY3RlZCBpbmZvcm1hdGlvbi5cbiAqIEBhcGkgcHJpdmF0ZVxuICovXG5mdW5jdGlvbiBleHRyYWN0UHJvdG9jb2woYWRkcmVzcykge1xuICB2YXIgbWF0Y2ggPSBwcm90b2NvbHJlLmV4ZWMoYWRkcmVzcyk7XG5cbiAgcmV0dXJuIHtcbiAgICBwcm90b2NvbDogbWF0Y2hbMV0gPyBtYXRjaFsxXS50b0xvd2VyQ2FzZSgpIDogJycsXG4gICAgc2xhc2hlczogISFtYXRjaFsyXSxcbiAgICByZXN0OiBtYXRjaFszXVxuICB9O1xufVxuXG4vKipcbiAqIFJlc29sdmUgYSByZWxhdGl2ZSBVUkwgcGF0aG5hbWUgYWdhaW5zdCBhIGJhc2UgVVJMIHBhdGhuYW1lLlxuICpcbiAqIEBwYXJhbSB7U3RyaW5nfSByZWxhdGl2ZSBQYXRobmFtZSBvZiB0aGUgcmVsYXRpdmUgVVJMLlxuICogQHBhcmFtIHtTdHJpbmd9IGJhc2UgUGF0aG5hbWUgb2YgdGhlIGJhc2UgVVJMLlxuICogQHJldHVybiB7U3RyaW5nfSBSZXNvbHZlZCBwYXRobmFtZS5cbiAqIEBhcGkgcHJpdmF0ZVxuICovXG5mdW5jdGlvbiByZXNvbHZlKHJlbGF0aXZlLCBiYXNlKSB7XG4gIHZhciBwYXRoID0gKGJhc2UgfHwgJy8nKS5zcGxpdCgnLycpLnNsaWNlKDAsIC0xKS5jb25jYXQocmVsYXRpdmUuc3BsaXQoJy8nKSlcbiAgICAsIGkgPSBwYXRoLmxlbmd0aFxuICAgICwgbGFzdCA9IHBhdGhbaSAtIDFdXG4gICAgLCB1bnNoaWZ0ID0gZmFsc2VcbiAgICAsIHVwID0gMDtcblxuICB3aGlsZSAoaS0tKSB7XG4gICAgaWYgKHBhdGhbaV0gPT09ICcuJykge1xuICAgICAgcGF0aC5zcGxpY2UoaSwgMSk7XG4gICAgfSBlbHNlIGlmIChwYXRoW2ldID09PSAnLi4nKSB7XG4gICAgICBwYXRoLnNwbGljZShpLCAxKTtcbiAgICAgIHVwKys7XG4gICAgfSBlbHNlIGlmICh1cCkge1xuICAgICAgaWYgKGkgPT09IDApIHVuc2hpZnQgPSB0cnVlO1xuICAgICAgcGF0aC5zcGxpY2UoaSwgMSk7XG4gICAgICB1cC0tO1xuICAgIH1cbiAgfVxuXG4gIGlmICh1bnNoaWZ0KSBwYXRoLnVuc2hpZnQoJycpO1xuICBpZiAobGFzdCA9PT0gJy4nIHx8IGxhc3QgPT09ICcuLicpIHBhdGgucHVzaCgnJyk7XG5cbiAgcmV0dXJuIHBhdGguam9pbignLycpO1xufVxuXG4vKipcbiAqIFRoZSBhY3R1YWwgVVJMIGluc3RhbmNlLiBJbnN0ZWFkIG9mIHJldHVybmluZyBhbiBvYmplY3Qgd2UndmUgb3B0ZWQtaW4gdG9cbiAqIGNyZWF0ZSBhbiBhY3R1YWwgY29uc3RydWN0b3IgYXMgaXQncyBtdWNoIG1vcmUgbWVtb3J5IGVmZmljaWVudCBhbmRcbiAqIGZhc3RlciBhbmQgaXQgcGxlYXNlcyBteSBPQ0QuXG4gKlxuICogQGNvbnN0cnVjdG9yXG4gKiBAcGFyYW0ge1N0cmluZ30gYWRkcmVzcyBVUkwgd2Ugd2FudCB0byBwYXJzZS5cbiAqIEBwYXJhbSB7T2JqZWN0fFN0cmluZ30gbG9jYXRpb24gTG9jYXRpb24gZGVmYXVsdHMgZm9yIHJlbGF0aXZlIHBhdGhzLlxuICogQHBhcmFtIHtCb29sZWFufEZ1bmN0aW9ufSBwYXJzZXIgUGFyc2VyIGZvciB0aGUgcXVlcnkgc3RyaW5nLlxuICogQGFwaSBwdWJsaWNcbiAqL1xuZnVuY3Rpb24gVVJMKGFkZHJlc3MsIGxvY2F0aW9uLCBwYXJzZXIpIHtcbiAgaWYgKCEodGhpcyBpbnN0YW5jZW9mIFVSTCkpIHtcbiAgICByZXR1cm4gbmV3IFVSTChhZGRyZXNzLCBsb2NhdGlvbiwgcGFyc2VyKTtcbiAgfVxuXG4gIHZhciByZWxhdGl2ZSwgZXh0cmFjdGVkLCBwYXJzZSwgaW5zdHJ1Y3Rpb24sIGluZGV4LCBrZXlcbiAgICAsIGluc3RydWN0aW9ucyA9IHJ1bGVzLnNsaWNlKClcbiAgICAsIHR5cGUgPSB0eXBlb2YgbG9jYXRpb25cbiAgICAsIHVybCA9IHRoaXNcbiAgICAsIGkgPSAwO1xuXG4gIC8vXG4gIC8vIFRoZSBmb2xsb3dpbmcgaWYgc3RhdGVtZW50cyBhbGxvd3MgdGhpcyBtb2R1bGUgdHdvIGhhdmUgY29tcGF0aWJpbGl0eSB3aXRoXG4gIC8vIDIgZGlmZmVyZW50IEFQSTpcbiAgLy9cbiAgLy8gMS4gTm9kZS5qcydzIGB1cmwucGFyc2VgIGFwaSB3aGljaCBhY2NlcHRzIGEgVVJMLCBib29sZWFuIGFzIGFyZ3VtZW50c1xuICAvLyAgICB3aGVyZSB0aGUgYm9vbGVhbiBpbmRpY2F0ZXMgdGhhdCB0aGUgcXVlcnkgc3RyaW5nIHNob3VsZCBhbHNvIGJlIHBhcnNlZC5cbiAgLy9cbiAgLy8gMi4gVGhlIGBVUkxgIGludGVyZmFjZSBvZiB0aGUgYnJvd3NlciB3aGljaCBhY2NlcHRzIGEgVVJMLCBvYmplY3QgYXNcbiAgLy8gICAgYXJndW1lbnRzLiBUaGUgc3VwcGxpZWQgb2JqZWN0IHdpbGwgYmUgdXNlZCBhcyBkZWZhdWx0IHZhbHVlcyAvIGZhbGwtYmFja1xuICAvLyAgICBmb3IgcmVsYXRpdmUgcGF0aHMuXG4gIC8vXG4gIGlmICgnb2JqZWN0JyAhPT0gdHlwZSAmJiAnc3RyaW5nJyAhPT0gdHlwZSkge1xuICAgIHBhcnNlciA9IGxvY2F0aW9uO1xuICAgIGxvY2F0aW9uID0gbnVsbDtcbiAgfVxuXG4gIGlmIChwYXJzZXIgJiYgJ2Z1bmN0aW9uJyAhPT0gdHlwZW9mIHBhcnNlcikgcGFyc2VyID0gcXMucGFyc2U7XG5cbiAgbG9jYXRpb24gPSBsb2xjYXRpb24obG9jYXRpb24pO1xuXG4gIC8vXG4gIC8vIEV4dHJhY3QgcHJvdG9jb2wgaW5mb3JtYXRpb24gYmVmb3JlIHJ1bm5pbmcgdGhlIGluc3RydWN0aW9ucy5cbiAgLy9cbiAgZXh0cmFjdGVkID0gZXh0cmFjdFByb3RvY29sKGFkZHJlc3MgfHwgJycpO1xuICByZWxhdGl2ZSA9ICFleHRyYWN0ZWQucHJvdG9jb2wgJiYgIWV4dHJhY3RlZC5zbGFzaGVzO1xuICB1cmwuc2xhc2hlcyA9IGV4dHJhY3RlZC5zbGFzaGVzIHx8IHJlbGF0aXZlICYmIGxvY2F0aW9uLnNsYXNoZXM7XG4gIHVybC5wcm90b2NvbCA9IGV4dHJhY3RlZC5wcm90b2NvbCB8fCBsb2NhdGlvbi5wcm90b2NvbCB8fCAnJztcbiAgYWRkcmVzcyA9IGV4dHJhY3RlZC5yZXN0O1xuXG4gIC8vXG4gIC8vIFdoZW4gdGhlIGF1dGhvcml0eSBjb21wb25lbnQgaXMgYWJzZW50IHRoZSBVUkwgc3RhcnRzIHdpdGggYSBwYXRoXG4gIC8vIGNvbXBvbmVudC5cbiAgLy9cbiAgaWYgKCFleHRyYWN0ZWQuc2xhc2hlcykgaW5zdHJ1Y3Rpb25zWzJdID0gWy8oLiopLywgJ3BhdGhuYW1lJ107XG5cbiAgZm9yICg7IGkgPCBpbnN0cnVjdGlvbnMubGVuZ3RoOyBpKyspIHtcbiAgICBpbnN0cnVjdGlvbiA9IGluc3RydWN0aW9uc1tpXTtcbiAgICBwYXJzZSA9IGluc3RydWN0aW9uWzBdO1xuICAgIGtleSA9IGluc3RydWN0aW9uWzFdO1xuXG4gICAgaWYgKHBhcnNlICE9PSBwYXJzZSkge1xuICAgICAgdXJsW2tleV0gPSBhZGRyZXNzO1xuICAgIH0gZWxzZSBpZiAoJ3N0cmluZycgPT09IHR5cGVvZiBwYXJzZSkge1xuICAgICAgaWYgKH4oaW5kZXggPSBhZGRyZXNzLmluZGV4T2YocGFyc2UpKSkge1xuICAgICAgICBpZiAoJ251bWJlcicgPT09IHR5cGVvZiBpbnN0cnVjdGlvblsyXSkge1xuICAgICAgICAgIHVybFtrZXldID0gYWRkcmVzcy5zbGljZSgwLCBpbmRleCk7XG4gICAgICAgICAgYWRkcmVzcyA9IGFkZHJlc3Muc2xpY2UoaW5kZXggKyBpbnN0cnVjdGlvblsyXSk7XG4gICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgdXJsW2tleV0gPSBhZGRyZXNzLnNsaWNlKGluZGV4KTtcbiAgICAgICAgICBhZGRyZXNzID0gYWRkcmVzcy5zbGljZSgwLCBpbmRleCk7XG4gICAgICAgIH1cbiAgICAgIH1cbiAgICB9IGVsc2UgaWYgKGluZGV4ID0gcGFyc2UuZXhlYyhhZGRyZXNzKSkge1xuICAgICAgdXJsW2tleV0gPSBpbmRleFsxXTtcbiAgICAgIGFkZHJlc3MgPSBhZGRyZXNzLnNsaWNlKDAsIGluZGV4LmluZGV4KTtcbiAgICB9XG5cbiAgICB1cmxba2V5XSA9IHVybFtrZXldIHx8IChcbiAgICAgIHJlbGF0aXZlICYmIGluc3RydWN0aW9uWzNdID8gbG9jYXRpb25ba2V5XSB8fCAnJyA6ICcnXG4gICAgKTtcblxuICAgIC8vXG4gICAgLy8gSG9zdG5hbWUsIGhvc3QgYW5kIHByb3RvY29sIHNob3VsZCBiZSBsb3dlcmNhc2VkIHNvIHRoZXkgY2FuIGJlIHVzZWQgdG9cbiAgICAvLyBjcmVhdGUgYSBwcm9wZXIgYG9yaWdpbmAuXG4gICAgLy9cbiAgICBpZiAoaW5zdHJ1Y3Rpb25bNF0pIHVybFtrZXldID0gdXJsW2tleV0udG9Mb3dlckNhc2UoKTtcbiAgfVxuXG4gIC8vXG4gIC8vIEFsc28gcGFyc2UgdGhlIHN1cHBsaWVkIHF1ZXJ5IHN0cmluZyBpbiB0byBhbiBvYmplY3QuIElmIHdlJ3JlIHN1cHBsaWVkXG4gIC8vIHdpdGggYSBjdXN0b20gcGFyc2VyIGFzIGZ1bmN0aW9uIHVzZSB0aGF0IGluc3RlYWQgb2YgdGhlIGRlZmF1bHQgYnVpbGQtaW5cbiAgLy8gcGFyc2VyLlxuICAvL1xuICBpZiAocGFyc2VyKSB1cmwucXVlcnkgPSBwYXJzZXIodXJsLnF1ZXJ5KTtcblxuICAvL1xuICAvLyBJZiB0aGUgVVJMIGlzIHJlbGF0aXZlLCByZXNvbHZlIHRoZSBwYXRobmFtZSBhZ2FpbnN0IHRoZSBiYXNlIFVSTC5cbiAgLy9cbiAgaWYgKFxuICAgICAgcmVsYXRpdmVcbiAgICAmJiBsb2NhdGlvbi5zbGFzaGVzXG4gICAgJiYgdXJsLnBhdGhuYW1lLmNoYXJBdCgwKSAhPT0gJy8nXG4gICAgJiYgKHVybC5wYXRobmFtZSAhPT0gJycgfHwgbG9jYXRpb24ucGF0aG5hbWUgIT09ICcnKVxuICApIHtcbiAgICB1cmwucGF0aG5hbWUgPSByZXNvbHZlKHVybC5wYXRobmFtZSwgbG9jYXRpb24ucGF0aG5hbWUpO1xuICB9XG5cbiAgLy9cbiAgLy8gV2Ugc2hvdWxkIG5vdCBhZGQgcG9ydCBudW1iZXJzIGlmIHRoZXkgYXJlIGFscmVhZHkgdGhlIGRlZmF1bHQgcG9ydCBudW1iZXJcbiAgLy8gZm9yIGEgZ2l2ZW4gcHJvdG9jb2wuIEFzIHRoZSBob3N0IGFsc28gY29udGFpbnMgdGhlIHBvcnQgbnVtYmVyIHdlJ3JlIGdvaW5nXG4gIC8vIG92ZXJyaWRlIGl0IHdpdGggdGhlIGhvc3RuYW1lIHdoaWNoIGNvbnRhaW5zIG5vIHBvcnQgbnVtYmVyLlxuICAvL1xuICBpZiAoIXJlcXVpcmVkKHVybC5wb3J0LCB1cmwucHJvdG9jb2wpKSB7XG4gICAgdXJsLmhvc3QgPSB1cmwuaG9zdG5hbWU7XG4gICAgdXJsLnBvcnQgPSAnJztcbiAgfVxuXG4gIC8vXG4gIC8vIFBhcnNlIGRvd24gdGhlIGBhdXRoYCBmb3IgdGhlIHVzZXJuYW1lIGFuZCBwYXNzd29yZC5cbiAgLy9cbiAgdXJsLnVzZXJuYW1lID0gdXJsLnBhc3N3b3JkID0gJyc7XG4gIGlmICh1cmwuYXV0aCkge1xuICAgIGluc3RydWN0aW9uID0gdXJsLmF1dGguc3BsaXQoJzonKTtcbiAgICB1cmwudXNlcm5hbWUgPSBpbnN0cnVjdGlvblswXSB8fCAnJztcbiAgICB1cmwucGFzc3dvcmQgPSBpbnN0cnVjdGlvblsxXSB8fCAnJztcbiAgfVxuXG4gIHVybC5vcmlnaW4gPSB1cmwucHJvdG9jb2wgJiYgdXJsLmhvc3QgJiYgdXJsLnByb3RvY29sICE9PSAnZmlsZTonXG4gICAgPyB1cmwucHJvdG9jb2wgKycvLycrIHVybC5ob3N0XG4gICAgOiAnbnVsbCc7XG5cbiAgLy9cbiAgLy8gVGhlIGhyZWYgaXMganVzdCB0aGUgY29tcGlsZWQgcmVzdWx0LlxuICAvL1xuICB1cmwuaHJlZiA9IHVybC50b1N0cmluZygpO1xufVxuXG4vKipcbiAqIFRoaXMgaXMgY29udmVuaWVuY2UgbWV0aG9kIGZvciBjaGFuZ2luZyBwcm9wZXJ0aWVzIGluIHRoZSBVUkwgaW5zdGFuY2UgdG9cbiAqIGluc3VyZSB0aGF0IHRoZXkgYWxsIHByb3BhZ2F0ZSBjb3JyZWN0bHkuXG4gKlxuICogQHBhcmFtIHtTdHJpbmd9IHBhcnQgICAgICAgICAgUHJvcGVydHkgd2UgbmVlZCB0byBhZGp1c3QuXG4gKiBAcGFyYW0ge01peGVkfSB2YWx1ZSAgICAgICAgICBUaGUgbmV3bHkgYXNzaWduZWQgdmFsdWUuXG4gKiBAcGFyYW0ge0Jvb2xlYW58RnVuY3Rpb259IGZuICBXaGVuIHNldHRpbmcgdGhlIHF1ZXJ5LCBpdCB3aWxsIGJlIHRoZSBmdW5jdGlvblxuICogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgdXNlZCB0byBwYXJzZSB0aGUgcXVlcnkuXG4gKiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBXaGVuIHNldHRpbmcgdGhlIHByb3RvY29sLCBkb3VibGUgc2xhc2ggd2lsbCBiZVxuICogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgcmVtb3ZlZCBmcm9tIHRoZSBmaW5hbCB1cmwgaWYgaXQgaXMgdHJ1ZS5cbiAqIEByZXR1cm5zIHtVUkx9XG4gKiBAYXBpIHB1YmxpY1xuICovXG5VUkwucHJvdG90eXBlLnNldCA9IGZ1bmN0aW9uIHNldChwYXJ0LCB2YWx1ZSwgZm4pIHtcbiAgdmFyIHVybCA9IHRoaXM7XG5cbiAgc3dpdGNoIChwYXJ0KSB7XG4gICAgY2FzZSAncXVlcnknOlxuICAgICAgaWYgKCdzdHJpbmcnID09PSB0eXBlb2YgdmFsdWUgJiYgdmFsdWUubGVuZ3RoKSB7XG4gICAgICAgIHZhbHVlID0gKGZuIHx8IHFzLnBhcnNlKSh2YWx1ZSk7XG4gICAgICB9XG5cbiAgICAgIHVybFtwYXJ0XSA9IHZhbHVlO1xuICAgICAgYnJlYWs7XG5cbiAgICBjYXNlICdwb3J0JzpcbiAgICAgIHVybFtwYXJ0XSA9IHZhbHVlO1xuXG4gICAgICBpZiAoIXJlcXVpcmVkKHZhbHVlLCB1cmwucHJvdG9jb2wpKSB7XG4gICAgICAgIHVybC5ob3N0ID0gdXJsLmhvc3RuYW1lO1xuICAgICAgICB1cmxbcGFydF0gPSAnJztcbiAgICAgIH0gZWxzZSBpZiAodmFsdWUpIHtcbiAgICAgICAgdXJsLmhvc3QgPSB1cmwuaG9zdG5hbWUgKyc6JysgdmFsdWU7XG4gICAgICB9XG5cbiAgICAgIGJyZWFrO1xuXG4gICAgY2FzZSAnaG9zdG5hbWUnOlxuICAgICAgdXJsW3BhcnRdID0gdmFsdWU7XG5cbiAgICAgIGlmICh1cmwucG9ydCkgdmFsdWUgKz0gJzonKyB1cmwucG9ydDtcbiAgICAgIHVybC5ob3N0ID0gdmFsdWU7XG4gICAgICBicmVhaztcblxuICAgIGNhc2UgJ2hvc3QnOlxuICAgICAgdXJsW3BhcnRdID0gdmFsdWU7XG5cbiAgICAgIGlmICgvOlxcZCskLy50ZXN0KHZhbHVlKSkge1xuICAgICAgICB2YWx1ZSA9IHZhbHVlLnNwbGl0KCc6Jyk7XG4gICAgICAgIHVybC5wb3J0ID0gdmFsdWUucG9wKCk7XG4gICAgICAgIHVybC5ob3N0bmFtZSA9IHZhbHVlLmpvaW4oJzonKTtcbiAgICAgIH0gZWxzZSB7XG4gICAgICAgIHVybC5ob3N0bmFtZSA9IHZhbHVlO1xuICAgICAgICB1cmwucG9ydCA9ICcnO1xuICAgICAgfVxuXG4gICAgICBicmVhaztcblxuICAgIGNhc2UgJ3Byb3RvY29sJzpcbiAgICAgIHVybC5wcm90b2NvbCA9IHZhbHVlLnRvTG93ZXJDYXNlKCk7XG4gICAgICB1cmwuc2xhc2hlcyA9ICFmbjtcbiAgICAgIGJyZWFrO1xuXG4gICAgY2FzZSAncGF0aG5hbWUnOlxuICAgICAgdXJsLnBhdGhuYW1lID0gdmFsdWUubGVuZ3RoICYmIHZhbHVlLmNoYXJBdCgwKSAhPT0gJy8nID8gJy8nICsgdmFsdWUgOiB2YWx1ZTtcblxuICAgICAgYnJlYWs7XG5cbiAgICBkZWZhdWx0OlxuICAgICAgdXJsW3BhcnRdID0gdmFsdWU7XG4gIH1cblxuICBmb3IgKHZhciBpID0gMDsgaSA8IHJ1bGVzLmxlbmd0aDsgaSsrKSB7XG4gICAgdmFyIGlucyA9IHJ1bGVzW2ldO1xuXG4gICAgaWYgKGluc1s0XSkgdXJsW2luc1sxXV0gPSB1cmxbaW5zWzFdXS50b0xvd2VyQ2FzZSgpO1xuICB9XG5cbiAgdXJsLm9yaWdpbiA9IHVybC5wcm90b2NvbCAmJiB1cmwuaG9zdCAmJiB1cmwucHJvdG9jb2wgIT09ICdmaWxlOidcbiAgICA/IHVybC5wcm90b2NvbCArJy8vJysgdXJsLmhvc3RcbiAgICA6ICdudWxsJztcblxuICB1cmwuaHJlZiA9IHVybC50b1N0cmluZygpO1xuXG4gIHJldHVybiB1cmw7XG59O1xuXG4vKipcbiAqIFRyYW5zZm9ybSB0aGUgcHJvcGVydGllcyBiYWNrIGluIHRvIGEgdmFsaWQgYW5kIGZ1bGwgVVJMIHN0cmluZy5cbiAqXG4gKiBAcGFyYW0ge0Z1bmN0aW9ufSBzdHJpbmdpZnkgT3B0aW9uYWwgcXVlcnkgc3RyaW5naWZ5IGZ1bmN0aW9uLlxuICogQHJldHVybnMge1N0cmluZ31cbiAqIEBhcGkgcHVibGljXG4gKi9cblVSTC5wcm90b3R5cGUudG9TdHJpbmcgPSBmdW5jdGlvbiB0b1N0cmluZyhzdHJpbmdpZnkpIHtcbiAgaWYgKCFzdHJpbmdpZnkgfHwgJ2Z1bmN0aW9uJyAhPT0gdHlwZW9mIHN0cmluZ2lmeSkgc3RyaW5naWZ5ID0gcXMuc3RyaW5naWZ5O1xuXG4gIHZhciBxdWVyeVxuICAgICwgdXJsID0gdGhpc1xuICAgICwgcHJvdG9jb2wgPSB1cmwucHJvdG9jb2w7XG5cbiAgaWYgKHByb3RvY29sICYmIHByb3RvY29sLmNoYXJBdChwcm90b2NvbC5sZW5ndGggLSAxKSAhPT0gJzonKSBwcm90b2NvbCArPSAnOic7XG5cbiAgdmFyIHJlc3VsdCA9IHByb3RvY29sICsgKHVybC5zbGFzaGVzID8gJy8vJyA6ICcnKTtcblxuICBpZiAodXJsLnVzZXJuYW1lKSB7XG4gICAgcmVzdWx0ICs9IHVybC51c2VybmFtZTtcbiAgICBpZiAodXJsLnBhc3N3b3JkKSByZXN1bHQgKz0gJzonKyB1cmwucGFzc3dvcmQ7XG4gICAgcmVzdWx0ICs9ICdAJztcbiAgfVxuXG4gIHJlc3VsdCArPSB1cmwuaG9zdCArIHVybC5wYXRobmFtZTtcblxuICBxdWVyeSA9ICdvYmplY3QnID09PSB0eXBlb2YgdXJsLnF1ZXJ5ID8gc3RyaW5naWZ5KHVybC5xdWVyeSkgOiB1cmwucXVlcnk7XG4gIGlmIChxdWVyeSkgcmVzdWx0ICs9ICc/JyAhPT0gcXVlcnkuY2hhckF0KDApID8gJz8nKyBxdWVyeSA6IHF1ZXJ5O1xuXG4gIGlmICh1cmwuaGFzaCkgcmVzdWx0ICs9IHVybC5oYXNoO1xuXG4gIHJldHVybiByZXN1bHQ7XG59O1xuXG4vL1xuLy8gRXhwb3NlIHRoZSBVUkwgcGFyc2VyIGFuZCBzb21lIGFkZGl0aW9uYWwgcHJvcGVydGllcyB0aGF0IG1pZ2h0IGJlIHVzZWZ1bCBmb3Jcbi8vIG90aGVycyBvciB0ZXN0aW5nLlxuLy9cblVSTC5leHRyYWN0UHJvdG9jb2wgPSBleHRyYWN0UHJvdG9jb2w7XG5VUkwubG9jYXRpb24gPSBsb2xjYXRpb247XG5VUkwucXMgPSBxcztcblxubW9kdWxlLmV4cG9ydHMgPSBVUkw7XG4iLCIndXNlIHN0cmljdCc7XG5cbnZhciBzbGFzaGVzID0gL15bQS1aYS16XVtBLVphLXowLTkrLS5dKjpcXC9cXC8vO1xuXG4vKipcbiAqIFRoZXNlIHByb3BlcnRpZXMgc2hvdWxkIG5vdCBiZSBjb3BpZWQgb3IgaW5oZXJpdGVkIGZyb20uIFRoaXMgaXMgb25seSBuZWVkZWRcbiAqIGZvciBhbGwgbm9uIGJsb2IgVVJMJ3MgYXMgYSBibG9iIFVSTCBkb2VzIG5vdCBpbmNsdWRlIGEgaGFzaCwgb25seSB0aGVcbiAqIG9yaWdpbi5cbiAqXG4gKiBAdHlwZSB7T2JqZWN0fVxuICogQHByaXZhdGVcbiAqL1xudmFyIGlnbm9yZSA9IHsgaGFzaDogMSwgcXVlcnk6IDEgfVxuICAsIFVSTDtcblxuLyoqXG4gKiBUaGUgbG9jYXRpb24gb2JqZWN0IGRpZmZlcnMgd2hlbiB5b3VyIGNvZGUgaXMgbG9hZGVkIHRocm91Z2ggYSBub3JtYWwgcGFnZSxcbiAqIFdvcmtlciBvciB0aHJvdWdoIGEgd29ya2VyIHVzaW5nIGEgYmxvYi4gQW5kIHdpdGggdGhlIGJsb2JibGUgYmVnaW5zIHRoZVxuICogdHJvdWJsZSBhcyB0aGUgbG9jYXRpb24gb2JqZWN0IHdpbGwgY29udGFpbiB0aGUgVVJMIG9mIHRoZSBibG9iLCBub3QgdGhlXG4gKiBsb2NhdGlvbiBvZiB0aGUgcGFnZSB3aGVyZSBvdXIgY29kZSBpcyBsb2FkZWQgaW4uIFRoZSBhY3R1YWwgb3JpZ2luIGlzXG4gKiBlbmNvZGVkIGluIHRoZSBgcGF0aG5hbWVgIHNvIHdlIGNhbiB0aGFua2Z1bGx5IGdlbmVyYXRlIGEgZ29vZCBcImRlZmF1bHRcIlxuICogbG9jYXRpb24gZnJvbSBpdCBzbyB3ZSBjYW4gZ2VuZXJhdGUgcHJvcGVyIHJlbGF0aXZlIFVSTCdzIGFnYWluLlxuICpcbiAqIEBwYXJhbSB7T2JqZWN0fFN0cmluZ30gbG9jIE9wdGlvbmFsIGRlZmF1bHQgbG9jYXRpb24gb2JqZWN0LlxuICogQHJldHVybnMge09iamVjdH0gbG9sY2F0aW9uIG9iamVjdC5cbiAqIEBhcGkgcHVibGljXG4gKi9cbm1vZHVsZS5leHBvcnRzID0gZnVuY3Rpb24gbG9sY2F0aW9uKGxvYykge1xuICBsb2MgPSBsb2MgfHwgZ2xvYmFsLmxvY2F0aW9uIHx8IHt9O1xuICBVUkwgPSBVUkwgfHwgcmVxdWlyZSgnLi8nKTtcblxuICB2YXIgZmluYWxkZXN0aW5hdGlvbiA9IHt9XG4gICAgLCB0eXBlID0gdHlwZW9mIGxvY1xuICAgICwga2V5O1xuXG4gIGlmICgnYmxvYjonID09PSBsb2MucHJvdG9jb2wpIHtcbiAgICBmaW5hbGRlc3RpbmF0aW9uID0gbmV3IFVSTCh1bmVzY2FwZShsb2MucGF0aG5hbWUpLCB7fSk7XG4gIH0gZWxzZSBpZiAoJ3N0cmluZycgPT09IHR5cGUpIHtcbiAgICBmaW5hbGRlc3RpbmF0aW9uID0gbmV3IFVSTChsb2MsIHt9KTtcbiAgICBmb3IgKGtleSBpbiBpZ25vcmUpIGRlbGV0ZSBmaW5hbGRlc3RpbmF0aW9uW2tleV07XG4gIH0gZWxzZSBpZiAoJ29iamVjdCcgPT09IHR5cGUpIHtcbiAgICBmb3IgKGtleSBpbiBsb2MpIHtcbiAgICAgIGlmIChrZXkgaW4gaWdub3JlKSBjb250aW51ZTtcbiAgICAgIGZpbmFsZGVzdGluYXRpb25ba2V5XSA9IGxvY1trZXldO1xuICAgIH1cblxuICAgIGlmIChmaW5hbGRlc3RpbmF0aW9uLnNsYXNoZXMgPT09IHVuZGVmaW5lZCkge1xuICAgICAgZmluYWxkZXN0aW5hdGlvbi5zbGFzaGVzID0gc2xhc2hlcy50ZXN0KGxvYy5ocmVmKTtcbiAgICB9XG4gIH1cblxuICByZXR1cm4gZmluYWxkZXN0aW5hdGlvbjtcbn07XG4iLCIoZnVuY3Rpb24gKHJvb3QsIGZhY3RvcnkpIHtcbiAgICBpZiAodHlwZW9mIGV4cG9ydHMgPT09ICdvYmplY3QnKSB7XG4gICAgICAgIG1vZHVsZS5leHBvcnRzID0gZmFjdG9yeSgpO1xuICAgIH0gZWxzZSBpZiAodHlwZW9mIGRlZmluZSA9PT0gJ2Z1bmN0aW9uJyAmJiBkZWZpbmUuYW1kKSB7XG4gICAgICAgIGRlZmluZShbXSwgZmFjdG9yeSk7XG4gICAgfSBlbHNlIHtcbiAgICAgICAgcm9vdC51cmx0ZW1wbGF0ZSA9IGZhY3RvcnkoKTtcbiAgICB9XG59KHRoaXMsIGZ1bmN0aW9uICgpIHtcbiAgLyoqXG4gICAqIEBjb25zdHJ1Y3RvclxuICAgKi9cbiAgZnVuY3Rpb24gVXJsVGVtcGxhdGUoKSB7XG4gIH1cblxuICAvKipcbiAgICogQHByaXZhdGVcbiAgICogQHBhcmFtIHtzdHJpbmd9IHN0clxuICAgKiBAcmV0dXJuIHtzdHJpbmd9XG4gICAqL1xuICBVcmxUZW1wbGF0ZS5wcm90b3R5cGUuZW5jb2RlUmVzZXJ2ZWQgPSBmdW5jdGlvbiAoc3RyKSB7XG4gICAgcmV0dXJuIHN0ci5zcGxpdCgvKCVbMC05QS1GYS1mXXsyfSkvZykubWFwKGZ1bmN0aW9uIChwYXJ0KSB7XG4gICAgICBpZiAoIS8lWzAtOUEtRmEtZl0vLnRlc3QocGFydCkpIHtcbiAgICAgICAgcGFydCA9IGVuY29kZVVSSShwYXJ0KS5yZXBsYWNlKC8lNUIvZywgJ1snKS5yZXBsYWNlKC8lNUQvZywgJ10nKTtcbiAgICAgIH1cbiAgICAgIHJldHVybiBwYXJ0O1xuICAgIH0pLmpvaW4oJycpO1xuICB9O1xuXG4gIC8qKlxuICAgKiBAcHJpdmF0ZVxuICAgKiBAcGFyYW0ge3N0cmluZ30gc3RyXG4gICAqIEByZXR1cm4ge3N0cmluZ31cbiAgICovXG4gIFVybFRlbXBsYXRlLnByb3RvdHlwZS5lbmNvZGVVbnJlc2VydmVkID0gZnVuY3Rpb24gKHN0cikge1xuICAgIHJldHVybiBlbmNvZGVVUklDb21wb25lbnQoc3RyKS5yZXBsYWNlKC9bIScoKSpdL2csIGZ1bmN0aW9uIChjKSB7XG4gICAgICByZXR1cm4gJyUnICsgYy5jaGFyQ29kZUF0KDApLnRvU3RyaW5nKDE2KS50b1VwcGVyQ2FzZSgpO1xuICAgIH0pO1xuICB9XG5cbiAgLyoqXG4gICAqIEBwcml2YXRlXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBvcGVyYXRvclxuICAgKiBAcGFyYW0ge3N0cmluZ30gdmFsdWVcbiAgICogQHBhcmFtIHtzdHJpbmd9IGtleVxuICAgKiBAcmV0dXJuIHtzdHJpbmd9XG4gICAqL1xuICBVcmxUZW1wbGF0ZS5wcm90b3R5cGUuZW5jb2RlVmFsdWUgPSBmdW5jdGlvbiAob3BlcmF0b3IsIHZhbHVlLCBrZXkpIHtcbiAgICB2YWx1ZSA9IChvcGVyYXRvciA9PT0gJysnIHx8IG9wZXJhdG9yID09PSAnIycpID8gdGhpcy5lbmNvZGVSZXNlcnZlZCh2YWx1ZSkgOiB0aGlzLmVuY29kZVVucmVzZXJ2ZWQodmFsdWUpO1xuXG4gICAgaWYgKGtleSkge1xuICAgICAgcmV0dXJuIHRoaXMuZW5jb2RlVW5yZXNlcnZlZChrZXkpICsgJz0nICsgdmFsdWU7XG4gICAgfSBlbHNlIHtcbiAgICAgIHJldHVybiB2YWx1ZTtcbiAgICB9XG4gIH07XG5cbiAgLyoqXG4gICAqIEBwcml2YXRlXG4gICAqIEBwYXJhbSB7Kn0gdmFsdWVcbiAgICogQHJldHVybiB7Ym9vbGVhbn1cbiAgICovXG4gIFVybFRlbXBsYXRlLnByb3RvdHlwZS5pc0RlZmluZWQgPSBmdW5jdGlvbiAodmFsdWUpIHtcbiAgICByZXR1cm4gdmFsdWUgIT09IHVuZGVmaW5lZCAmJiB2YWx1ZSAhPT0gbnVsbDtcbiAgfTtcblxuICAvKipcbiAgICogQHByaXZhdGVcbiAgICogQHBhcmFtIHtzdHJpbmd9XG4gICAqIEByZXR1cm4ge2Jvb2xlYW59XG4gICAqL1xuICBVcmxUZW1wbGF0ZS5wcm90b3R5cGUuaXNLZXlPcGVyYXRvciA9IGZ1bmN0aW9uIChvcGVyYXRvcikge1xuICAgIHJldHVybiBvcGVyYXRvciA9PT0gJzsnIHx8IG9wZXJhdG9yID09PSAnJicgfHwgb3BlcmF0b3IgPT09ICc/JztcbiAgfTtcblxuICAvKipcbiAgICogQHByaXZhdGVcbiAgICogQHBhcmFtIHtPYmplY3R9IGNvbnRleHRcbiAgICogQHBhcmFtIHtzdHJpbmd9IG9wZXJhdG9yXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBrZXlcbiAgICogQHBhcmFtIHtzdHJpbmd9IG1vZGlmaWVyXG4gICAqL1xuICBVcmxUZW1wbGF0ZS5wcm90b3R5cGUuZ2V0VmFsdWVzID0gZnVuY3Rpb24gKGNvbnRleHQsIG9wZXJhdG9yLCBrZXksIG1vZGlmaWVyKSB7XG4gICAgdmFyIHZhbHVlID0gY29udGV4dFtrZXldLFxuICAgICAgICByZXN1bHQgPSBbXTtcblxuICAgIGlmICh0aGlzLmlzRGVmaW5lZCh2YWx1ZSkgJiYgdmFsdWUgIT09ICcnKSB7XG4gICAgICBpZiAodHlwZW9mIHZhbHVlID09PSAnc3RyaW5nJyB8fCB0eXBlb2YgdmFsdWUgPT09ICdudW1iZXInIHx8IHR5cGVvZiB2YWx1ZSA9PT0gJ2Jvb2xlYW4nKSB7XG4gICAgICAgIHZhbHVlID0gdmFsdWUudG9TdHJpbmcoKTtcblxuICAgICAgICBpZiAobW9kaWZpZXIgJiYgbW9kaWZpZXIgIT09ICcqJykge1xuICAgICAgICAgIHZhbHVlID0gdmFsdWUuc3Vic3RyaW5nKDAsIHBhcnNlSW50KG1vZGlmaWVyLCAxMCkpO1xuICAgICAgICB9XG5cbiAgICAgICAgcmVzdWx0LnB1c2godGhpcy5lbmNvZGVWYWx1ZShvcGVyYXRvciwgdmFsdWUsIHRoaXMuaXNLZXlPcGVyYXRvcihvcGVyYXRvcikgPyBrZXkgOiBudWxsKSk7XG4gICAgICB9IGVsc2Uge1xuICAgICAgICBpZiAobW9kaWZpZXIgPT09ICcqJykge1xuICAgICAgICAgIGlmIChBcnJheS5pc0FycmF5KHZhbHVlKSkge1xuICAgICAgICAgICAgdmFsdWUuZmlsdGVyKHRoaXMuaXNEZWZpbmVkKS5mb3JFYWNoKGZ1bmN0aW9uICh2YWx1ZSkge1xuICAgICAgICAgICAgICByZXN1bHQucHVzaCh0aGlzLmVuY29kZVZhbHVlKG9wZXJhdG9yLCB2YWx1ZSwgdGhpcy5pc0tleU9wZXJhdG9yKG9wZXJhdG9yKSA/IGtleSA6IG51bGwpKTtcbiAgICAgICAgICAgIH0sIHRoaXMpO1xuICAgICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgICBPYmplY3Qua2V5cyh2YWx1ZSkuZm9yRWFjaChmdW5jdGlvbiAoaykge1xuICAgICAgICAgICAgICBpZiAodGhpcy5pc0RlZmluZWQodmFsdWVba10pKSB7XG4gICAgICAgICAgICAgICAgcmVzdWx0LnB1c2godGhpcy5lbmNvZGVWYWx1ZShvcGVyYXRvciwgdmFsdWVba10sIGspKTtcbiAgICAgICAgICAgICAgfVxuICAgICAgICAgICAgfSwgdGhpcyk7XG4gICAgICAgICAgfVxuICAgICAgICB9IGVsc2Uge1xuICAgICAgICAgIHZhciB0bXAgPSBbXTtcblxuICAgICAgICAgIGlmIChBcnJheS5pc0FycmF5KHZhbHVlKSkge1xuICAgICAgICAgICAgdmFsdWUuZmlsdGVyKHRoaXMuaXNEZWZpbmVkKS5mb3JFYWNoKGZ1bmN0aW9uICh2YWx1ZSkge1xuICAgICAgICAgICAgICB0bXAucHVzaCh0aGlzLmVuY29kZVZhbHVlKG9wZXJhdG9yLCB2YWx1ZSkpO1xuICAgICAgICAgICAgfSwgdGhpcyk7XG4gICAgICAgICAgfSBlbHNlIHtcbiAgICAgICAgICAgIE9iamVjdC5rZXlzKHZhbHVlKS5mb3JFYWNoKGZ1bmN0aW9uIChrKSB7XG4gICAgICAgICAgICAgIGlmICh0aGlzLmlzRGVmaW5lZCh2YWx1ZVtrXSkpIHtcbiAgICAgICAgICAgICAgICB0bXAucHVzaCh0aGlzLmVuY29kZVVucmVzZXJ2ZWQoaykpO1xuICAgICAgICAgICAgICAgIHRtcC5wdXNoKHRoaXMuZW5jb2RlVmFsdWUob3BlcmF0b3IsIHZhbHVlW2tdLnRvU3RyaW5nKCkpKTtcbiAgICAgICAgICAgICAgfVxuICAgICAgICAgICAgfSwgdGhpcyk7XG4gICAgICAgICAgfVxuXG4gICAgICAgICAgaWYgKHRoaXMuaXNLZXlPcGVyYXRvcihvcGVyYXRvcikpIHtcbiAgICAgICAgICAgIHJlc3VsdC5wdXNoKHRoaXMuZW5jb2RlVW5yZXNlcnZlZChrZXkpICsgJz0nICsgdG1wLmpvaW4oJywnKSk7XG4gICAgICAgICAgfSBlbHNlIGlmICh0bXAubGVuZ3RoICE9PSAwKSB7XG4gICAgICAgICAgICByZXN1bHQucHVzaCh0bXAuam9pbignLCcpKTtcbiAgICAgICAgICB9XG4gICAgICAgIH1cbiAgICAgIH1cbiAgICB9IGVsc2Uge1xuICAgICAgaWYgKG9wZXJhdG9yID09PSAnOycpIHtcbiAgICAgICAgaWYgKHRoaXMuaXNEZWZpbmVkKHZhbHVlKSkge1xuICAgICAgICAgIHJlc3VsdC5wdXNoKHRoaXMuZW5jb2RlVW5yZXNlcnZlZChrZXkpKTtcbiAgICAgICAgfVxuICAgICAgfSBlbHNlIGlmICh2YWx1ZSA9PT0gJycgJiYgKG9wZXJhdG9yID09PSAnJicgfHwgb3BlcmF0b3IgPT09ICc/JykpIHtcbiAgICAgICAgcmVzdWx0LnB1c2godGhpcy5lbmNvZGVVbnJlc2VydmVkKGtleSkgKyAnPScpO1xuICAgICAgfSBlbHNlIGlmICh2YWx1ZSA9PT0gJycpIHtcbiAgICAgICAgcmVzdWx0LnB1c2goJycpO1xuICAgICAgfVxuICAgIH1cbiAgICByZXR1cm4gcmVzdWx0O1xuICB9O1xuXG4gIC8qKlxuICAgKiBAcGFyYW0ge3N0cmluZ30gdGVtcGxhdGVcbiAgICogQHJldHVybiB7ZnVuY3Rpb24oT2JqZWN0KTpzdHJpbmd9XG4gICAqL1xuICBVcmxUZW1wbGF0ZS5wcm90b3R5cGUucGFyc2UgPSBmdW5jdGlvbiAodGVtcGxhdGUpIHtcbiAgICB2YXIgdGhhdCA9IHRoaXM7XG4gICAgdmFyIG9wZXJhdG9ycyA9IFsnKycsICcjJywgJy4nLCAnLycsICc7JywgJz8nLCAnJiddO1xuXG4gICAgcmV0dXJuIHtcbiAgICAgIGV4cGFuZDogZnVuY3Rpb24gKGNvbnRleHQpIHtcbiAgICAgICAgcmV0dXJuIHRlbXBsYXRlLnJlcGxhY2UoL1xceyhbXlxce1xcfV0rKVxcfXwoW15cXHtcXH1dKykvZywgZnVuY3Rpb24gKF8sIGV4cHJlc3Npb24sIGxpdGVyYWwpIHtcbiAgICAgICAgICBpZiAoZXhwcmVzc2lvbikge1xuICAgICAgICAgICAgdmFyIG9wZXJhdG9yID0gbnVsbCxcbiAgICAgICAgICAgICAgICB2YWx1ZXMgPSBbXTtcblxuICAgICAgICAgICAgaWYgKG9wZXJhdG9ycy5pbmRleE9mKGV4cHJlc3Npb24uY2hhckF0KDApKSAhPT0gLTEpIHtcbiAgICAgICAgICAgICAgb3BlcmF0b3IgPSBleHByZXNzaW9uLmNoYXJBdCgwKTtcbiAgICAgICAgICAgICAgZXhwcmVzc2lvbiA9IGV4cHJlc3Npb24uc3Vic3RyKDEpO1xuICAgICAgICAgICAgfVxuXG4gICAgICAgICAgICBleHByZXNzaW9uLnNwbGl0KC8sL2cpLmZvckVhY2goZnVuY3Rpb24gKHZhcmlhYmxlKSB7XG4gICAgICAgICAgICAgIHZhciB0bXAgPSAvKFteOlxcKl0qKSg/OjooXFxkKyl8KFxcKikpPy8uZXhlYyh2YXJpYWJsZSk7XG4gICAgICAgICAgICAgIHZhbHVlcy5wdXNoLmFwcGx5KHZhbHVlcywgdGhhdC5nZXRWYWx1ZXMoY29udGV4dCwgb3BlcmF0b3IsIHRtcFsxXSwgdG1wWzJdIHx8IHRtcFszXSkpO1xuICAgICAgICAgICAgfSk7XG5cbiAgICAgICAgICAgIGlmIChvcGVyYXRvciAmJiBvcGVyYXRvciAhPT0gJysnKSB7XG4gICAgICAgICAgICAgIHZhciBzZXBhcmF0b3IgPSAnLCc7XG5cbiAgICAgICAgICAgICAgaWYgKG9wZXJhdG9yID09PSAnPycpIHtcbiAgICAgICAgICAgICAgICBzZXBhcmF0b3IgPSAnJic7XG4gICAgICAgICAgICAgIH0gZWxzZSBpZiAob3BlcmF0b3IgIT09ICcjJykge1xuICAgICAgICAgICAgICAgIHNlcGFyYXRvciA9IG9wZXJhdG9yO1xuICAgICAgICAgICAgICB9XG4gICAgICAgICAgICAgIHJldHVybiAodmFsdWVzLmxlbmd0aCAhPT0gMCA/IG9wZXJhdG9yIDogJycpICsgdmFsdWVzLmpvaW4oc2VwYXJhdG9yKTtcbiAgICAgICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgICAgIHJldHVybiB2YWx1ZXMuam9pbignLCcpO1xuICAgICAgICAgICAgfVxuICAgICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgICByZXR1cm4gdGhhdC5lbmNvZGVSZXNlcnZlZChsaXRlcmFsKTtcbiAgICAgICAgICB9XG4gICAgICAgIH0pO1xuICAgICAgfVxuICAgIH07XG4gIH07XG5cbiAgcmV0dXJuIG5ldyBVcmxUZW1wbGF0ZSgpO1xufSkpO1xuIiwiKGZ1bmN0aW9uKHNlbGYpIHtcbiAgJ3VzZSBzdHJpY3QnO1xuXG4gIGlmIChzZWxmLmZldGNoKSB7XG4gICAgcmV0dXJuXG4gIH1cblxuICB2YXIgc3VwcG9ydCA9IHtcbiAgICBzZWFyY2hQYXJhbXM6ICdVUkxTZWFyY2hQYXJhbXMnIGluIHNlbGYsXG4gICAgaXRlcmFibGU6ICdTeW1ib2wnIGluIHNlbGYgJiYgJ2l0ZXJhdG9yJyBpbiBTeW1ib2wsXG4gICAgYmxvYjogJ0ZpbGVSZWFkZXInIGluIHNlbGYgJiYgJ0Jsb2InIGluIHNlbGYgJiYgKGZ1bmN0aW9uKCkge1xuICAgICAgdHJ5IHtcbiAgICAgICAgbmV3IEJsb2IoKVxuICAgICAgICByZXR1cm4gdHJ1ZVxuICAgICAgfSBjYXRjaChlKSB7XG4gICAgICAgIHJldHVybiBmYWxzZVxuICAgICAgfVxuICAgIH0pKCksXG4gICAgZm9ybURhdGE6ICdGb3JtRGF0YScgaW4gc2VsZixcbiAgICBhcnJheUJ1ZmZlcjogJ0FycmF5QnVmZmVyJyBpbiBzZWxmXG4gIH1cblxuICBpZiAoc3VwcG9ydC5hcnJheUJ1ZmZlcikge1xuICAgIHZhciB2aWV3Q2xhc3NlcyA9IFtcbiAgICAgICdbb2JqZWN0IEludDhBcnJheV0nLFxuICAgICAgJ1tvYmplY3QgVWludDhBcnJheV0nLFxuICAgICAgJ1tvYmplY3QgVWludDhDbGFtcGVkQXJyYXldJyxcbiAgICAgICdbb2JqZWN0IEludDE2QXJyYXldJyxcbiAgICAgICdbb2JqZWN0IFVpbnQxNkFycmF5XScsXG4gICAgICAnW29iamVjdCBJbnQzMkFycmF5XScsXG4gICAgICAnW29iamVjdCBVaW50MzJBcnJheV0nLFxuICAgICAgJ1tvYmplY3QgRmxvYXQzMkFycmF5XScsXG4gICAgICAnW29iamVjdCBGbG9hdDY0QXJyYXldJ1xuICAgIF1cblxuICAgIHZhciBpc0RhdGFWaWV3ID0gZnVuY3Rpb24ob2JqKSB7XG4gICAgICByZXR1cm4gb2JqICYmIERhdGFWaWV3LnByb3RvdHlwZS5pc1Byb3RvdHlwZU9mKG9iailcbiAgICB9XG5cbiAgICB2YXIgaXNBcnJheUJ1ZmZlclZpZXcgPSBBcnJheUJ1ZmZlci5pc1ZpZXcgfHwgZnVuY3Rpb24ob2JqKSB7XG4gICAgICByZXR1cm4gb2JqICYmIHZpZXdDbGFzc2VzLmluZGV4T2YoT2JqZWN0LnByb3RvdHlwZS50b1N0cmluZy5jYWxsKG9iaikpID4gLTFcbiAgICB9XG4gIH1cblxuICBmdW5jdGlvbiBub3JtYWxpemVOYW1lKG5hbWUpIHtcbiAgICBpZiAodHlwZW9mIG5hbWUgIT09ICdzdHJpbmcnKSB7XG4gICAgICBuYW1lID0gU3RyaW5nKG5hbWUpXG4gICAgfVxuICAgIGlmICgvW15hLXowLTlcXC0jJCUmJyorLlxcXl9gfH5dL2kudGVzdChuYW1lKSkge1xuICAgICAgdGhyb3cgbmV3IFR5cGVFcnJvcignSW52YWxpZCBjaGFyYWN0ZXIgaW4gaGVhZGVyIGZpZWxkIG5hbWUnKVxuICAgIH1cbiAgICByZXR1cm4gbmFtZS50b0xvd2VyQ2FzZSgpXG4gIH1cblxuICBmdW5jdGlvbiBub3JtYWxpemVWYWx1ZSh2YWx1ZSkge1xuICAgIGlmICh0eXBlb2YgdmFsdWUgIT09ICdzdHJpbmcnKSB7XG4gICAgICB2YWx1ZSA9IFN0cmluZyh2YWx1ZSlcbiAgICB9XG4gICAgcmV0dXJuIHZhbHVlXG4gIH1cblxuICAvLyBCdWlsZCBhIGRlc3RydWN0aXZlIGl0ZXJhdG9yIGZvciB0aGUgdmFsdWUgbGlzdFxuICBmdW5jdGlvbiBpdGVyYXRvckZvcihpdGVtcykge1xuICAgIHZhciBpdGVyYXRvciA9IHtcbiAgICAgIG5leHQ6IGZ1bmN0aW9uKCkge1xuICAgICAgICB2YXIgdmFsdWUgPSBpdGVtcy5zaGlmdCgpXG4gICAgICAgIHJldHVybiB7ZG9uZTogdmFsdWUgPT09IHVuZGVmaW5lZCwgdmFsdWU6IHZhbHVlfVxuICAgICAgfVxuICAgIH1cblxuICAgIGlmIChzdXBwb3J0Lml0ZXJhYmxlKSB7XG4gICAgICBpdGVyYXRvcltTeW1ib2wuaXRlcmF0b3JdID0gZnVuY3Rpb24oKSB7XG4gICAgICAgIHJldHVybiBpdGVyYXRvclxuICAgICAgfVxuICAgIH1cblxuICAgIHJldHVybiBpdGVyYXRvclxuICB9XG5cbiAgZnVuY3Rpb24gSGVhZGVycyhoZWFkZXJzKSB7XG4gICAgdGhpcy5tYXAgPSB7fVxuXG4gICAgaWYgKGhlYWRlcnMgaW5zdGFuY2VvZiBIZWFkZXJzKSB7XG4gICAgICBoZWFkZXJzLmZvckVhY2goZnVuY3Rpb24odmFsdWUsIG5hbWUpIHtcbiAgICAgICAgdGhpcy5hcHBlbmQobmFtZSwgdmFsdWUpXG4gICAgICB9LCB0aGlzKVxuXG4gICAgfSBlbHNlIGlmIChoZWFkZXJzKSB7XG4gICAgICBPYmplY3QuZ2V0T3duUHJvcGVydHlOYW1lcyhoZWFkZXJzKS5mb3JFYWNoKGZ1bmN0aW9uKG5hbWUpIHtcbiAgICAgICAgdGhpcy5hcHBlbmQobmFtZSwgaGVhZGVyc1tuYW1lXSlcbiAgICAgIH0sIHRoaXMpXG4gICAgfVxuICB9XG5cbiAgSGVhZGVycy5wcm90b3R5cGUuYXBwZW5kID0gZnVuY3Rpb24obmFtZSwgdmFsdWUpIHtcbiAgICBuYW1lID0gbm9ybWFsaXplTmFtZShuYW1lKVxuICAgIHZhbHVlID0gbm9ybWFsaXplVmFsdWUodmFsdWUpXG4gICAgdmFyIG9sZFZhbHVlID0gdGhpcy5tYXBbbmFtZV1cbiAgICB0aGlzLm1hcFtuYW1lXSA9IG9sZFZhbHVlID8gb2xkVmFsdWUrJywnK3ZhbHVlIDogdmFsdWVcbiAgfVxuXG4gIEhlYWRlcnMucHJvdG90eXBlWydkZWxldGUnXSA9IGZ1bmN0aW9uKG5hbWUpIHtcbiAgICBkZWxldGUgdGhpcy5tYXBbbm9ybWFsaXplTmFtZShuYW1lKV1cbiAgfVxuXG4gIEhlYWRlcnMucHJvdG90eXBlLmdldCA9IGZ1bmN0aW9uKG5hbWUpIHtcbiAgICBuYW1lID0gbm9ybWFsaXplTmFtZShuYW1lKVxuICAgIHJldHVybiB0aGlzLmhhcyhuYW1lKSA/IHRoaXMubWFwW25hbWVdIDogbnVsbFxuICB9XG5cbiAgSGVhZGVycy5wcm90b3R5cGUuaGFzID0gZnVuY3Rpb24obmFtZSkge1xuICAgIHJldHVybiB0aGlzLm1hcC5oYXNPd25Qcm9wZXJ0eShub3JtYWxpemVOYW1lKG5hbWUpKVxuICB9XG5cbiAgSGVhZGVycy5wcm90b3R5cGUuc2V0ID0gZnVuY3Rpb24obmFtZSwgdmFsdWUpIHtcbiAgICB0aGlzLm1hcFtub3JtYWxpemVOYW1lKG5hbWUpXSA9IG5vcm1hbGl6ZVZhbHVlKHZhbHVlKVxuICB9XG5cbiAgSGVhZGVycy5wcm90b3R5cGUuZm9yRWFjaCA9IGZ1bmN0aW9uKGNhbGxiYWNrLCB0aGlzQXJnKSB7XG4gICAgZm9yICh2YXIgbmFtZSBpbiB0aGlzLm1hcCkge1xuICAgICAgaWYgKHRoaXMubWFwLmhhc093blByb3BlcnR5KG5hbWUpKSB7XG4gICAgICAgIGNhbGxiYWNrLmNhbGwodGhpc0FyZywgdGhpcy5tYXBbbmFtZV0sIG5hbWUsIHRoaXMpXG4gICAgICB9XG4gICAgfVxuICB9XG5cbiAgSGVhZGVycy5wcm90b3R5cGUua2V5cyA9IGZ1bmN0aW9uKCkge1xuICAgIHZhciBpdGVtcyA9IFtdXG4gICAgdGhpcy5mb3JFYWNoKGZ1bmN0aW9uKHZhbHVlLCBuYW1lKSB7IGl0ZW1zLnB1c2gobmFtZSkgfSlcbiAgICByZXR1cm4gaXRlcmF0b3JGb3IoaXRlbXMpXG4gIH1cblxuICBIZWFkZXJzLnByb3RvdHlwZS52YWx1ZXMgPSBmdW5jdGlvbigpIHtcbiAgICB2YXIgaXRlbXMgPSBbXVxuICAgIHRoaXMuZm9yRWFjaChmdW5jdGlvbih2YWx1ZSkgeyBpdGVtcy5wdXNoKHZhbHVlKSB9KVxuICAgIHJldHVybiBpdGVyYXRvckZvcihpdGVtcylcbiAgfVxuXG4gIEhlYWRlcnMucHJvdG90eXBlLmVudHJpZXMgPSBmdW5jdGlvbigpIHtcbiAgICB2YXIgaXRlbXMgPSBbXVxuICAgIHRoaXMuZm9yRWFjaChmdW5jdGlvbih2YWx1ZSwgbmFtZSkgeyBpdGVtcy5wdXNoKFtuYW1lLCB2YWx1ZV0pIH0pXG4gICAgcmV0dXJuIGl0ZXJhdG9yRm9yKGl0ZW1zKVxuICB9XG5cbiAgaWYgKHN1cHBvcnQuaXRlcmFibGUpIHtcbiAgICBIZWFkZXJzLnByb3RvdHlwZVtTeW1ib2wuaXRlcmF0b3JdID0gSGVhZGVycy5wcm90b3R5cGUuZW50cmllc1xuICB9XG5cbiAgZnVuY3Rpb24gY29uc3VtZWQoYm9keSkge1xuICAgIGlmIChib2R5LmJvZHlVc2VkKSB7XG4gICAgICByZXR1cm4gUHJvbWlzZS5yZWplY3QobmV3IFR5cGVFcnJvcignQWxyZWFkeSByZWFkJykpXG4gICAgfVxuICAgIGJvZHkuYm9keVVzZWQgPSB0cnVlXG4gIH1cblxuICBmdW5jdGlvbiBmaWxlUmVhZGVyUmVhZHkocmVhZGVyKSB7XG4gICAgcmV0dXJuIG5ldyBQcm9taXNlKGZ1bmN0aW9uKHJlc29sdmUsIHJlamVjdCkge1xuICAgICAgcmVhZGVyLm9ubG9hZCA9IGZ1bmN0aW9uKCkge1xuICAgICAgICByZXNvbHZlKHJlYWRlci5yZXN1bHQpXG4gICAgICB9XG4gICAgICByZWFkZXIub25lcnJvciA9IGZ1bmN0aW9uKCkge1xuICAgICAgICByZWplY3QocmVhZGVyLmVycm9yKVxuICAgICAgfVxuICAgIH0pXG4gIH1cblxuICBmdW5jdGlvbiByZWFkQmxvYkFzQXJyYXlCdWZmZXIoYmxvYikge1xuICAgIHZhciByZWFkZXIgPSBuZXcgRmlsZVJlYWRlcigpXG4gICAgdmFyIHByb21pc2UgPSBmaWxlUmVhZGVyUmVhZHkocmVhZGVyKVxuICAgIHJlYWRlci5yZWFkQXNBcnJheUJ1ZmZlcihibG9iKVxuICAgIHJldHVybiBwcm9taXNlXG4gIH1cblxuICBmdW5jdGlvbiByZWFkQmxvYkFzVGV4dChibG9iKSB7XG4gICAgdmFyIHJlYWRlciA9IG5ldyBGaWxlUmVhZGVyKClcbiAgICB2YXIgcHJvbWlzZSA9IGZpbGVSZWFkZXJSZWFkeShyZWFkZXIpXG4gICAgcmVhZGVyLnJlYWRBc1RleHQoYmxvYilcbiAgICByZXR1cm4gcHJvbWlzZVxuICB9XG5cbiAgZnVuY3Rpb24gYnVmZmVyQ2xvbmUoYnVmKSB7XG4gICAgaWYgKGJ1Zi5zbGljZSkge1xuICAgICAgcmV0dXJuIGJ1Zi5zbGljZSgwKVxuICAgIH0gZWxzZSB7XG4gICAgICB2YXIgdmlldyA9IG5ldyBVaW50OEFycmF5KGJ1Zi5ieXRlTGVuZ3RoKVxuICAgICAgdmlldy5zZXQobmV3IFVpbnQ4QXJyYXkoYnVmKSlcbiAgICAgIHJldHVybiB2aWV3LmJ1ZmZlclxuICAgIH1cbiAgfVxuXG4gIGZ1bmN0aW9uIEJvZHkoKSB7XG4gICAgdGhpcy5ib2R5VXNlZCA9IGZhbHNlXG5cbiAgICB0aGlzLl9pbml0Qm9keSA9IGZ1bmN0aW9uKGJvZHkpIHtcbiAgICAgIHRoaXMuX2JvZHlJbml0ID0gYm9keVxuICAgICAgaWYgKCFib2R5KSB7XG4gICAgICAgIHRoaXMuX2JvZHlUZXh0ID0gJydcbiAgICAgIH0gZWxzZSBpZiAodHlwZW9mIGJvZHkgPT09ICdzdHJpbmcnKSB7XG4gICAgICAgIHRoaXMuX2JvZHlUZXh0ID0gYm9keVxuICAgICAgfSBlbHNlIGlmIChzdXBwb3J0LmJsb2IgJiYgQmxvYi5wcm90b3R5cGUuaXNQcm90b3R5cGVPZihib2R5KSkge1xuICAgICAgICB0aGlzLl9ib2R5QmxvYiA9IGJvZHlcbiAgICAgIH0gZWxzZSBpZiAoc3VwcG9ydC5mb3JtRGF0YSAmJiBGb3JtRGF0YS5wcm90b3R5cGUuaXNQcm90b3R5cGVPZihib2R5KSkge1xuICAgICAgICB0aGlzLl9ib2R5Rm9ybURhdGEgPSBib2R5XG4gICAgICB9IGVsc2UgaWYgKHN1cHBvcnQuc2VhcmNoUGFyYW1zICYmIFVSTFNlYXJjaFBhcmFtcy5wcm90b3R5cGUuaXNQcm90b3R5cGVPZihib2R5KSkge1xuICAgICAgICB0aGlzLl9ib2R5VGV4dCA9IGJvZHkudG9TdHJpbmcoKVxuICAgICAgfSBlbHNlIGlmIChzdXBwb3J0LmFycmF5QnVmZmVyICYmIHN1cHBvcnQuYmxvYiAmJiBpc0RhdGFWaWV3KGJvZHkpKSB7XG4gICAgICAgIHRoaXMuX2JvZHlBcnJheUJ1ZmZlciA9IGJ1ZmZlckNsb25lKGJvZHkuYnVmZmVyKVxuICAgICAgICAvLyBJRSAxMC0xMSBjYW4ndCBoYW5kbGUgYSBEYXRhVmlldyBib2R5LlxuICAgICAgICB0aGlzLl9ib2R5SW5pdCA9IG5ldyBCbG9iKFt0aGlzLl9ib2R5QXJyYXlCdWZmZXJdKVxuICAgICAgfSBlbHNlIGlmIChzdXBwb3J0LmFycmF5QnVmZmVyICYmIChBcnJheUJ1ZmZlci5wcm90b3R5cGUuaXNQcm90b3R5cGVPZihib2R5KSB8fCBpc0FycmF5QnVmZmVyVmlldyhib2R5KSkpIHtcbiAgICAgICAgdGhpcy5fYm9keUFycmF5QnVmZmVyID0gYnVmZmVyQ2xvbmUoYm9keSlcbiAgICAgIH0gZWxzZSB7XG4gICAgICAgIHRocm93IG5ldyBFcnJvcigndW5zdXBwb3J0ZWQgQm9keUluaXQgdHlwZScpXG4gICAgICB9XG5cbiAgICAgIGlmICghdGhpcy5oZWFkZXJzLmdldCgnY29udGVudC10eXBlJykpIHtcbiAgICAgICAgaWYgKHR5cGVvZiBib2R5ID09PSAnc3RyaW5nJykge1xuICAgICAgICAgIHRoaXMuaGVhZGVycy5zZXQoJ2NvbnRlbnQtdHlwZScsICd0ZXh0L3BsYWluO2NoYXJzZXQ9VVRGLTgnKVxuICAgICAgICB9IGVsc2UgaWYgKHRoaXMuX2JvZHlCbG9iICYmIHRoaXMuX2JvZHlCbG9iLnR5cGUpIHtcbiAgICAgICAgICB0aGlzLmhlYWRlcnMuc2V0KCdjb250ZW50LXR5cGUnLCB0aGlzLl9ib2R5QmxvYi50eXBlKVxuICAgICAgICB9IGVsc2UgaWYgKHN1cHBvcnQuc2VhcmNoUGFyYW1zICYmIFVSTFNlYXJjaFBhcmFtcy5wcm90b3R5cGUuaXNQcm90b3R5cGVPZihib2R5KSkge1xuICAgICAgICAgIHRoaXMuaGVhZGVycy5zZXQoJ2NvbnRlbnQtdHlwZScsICdhcHBsaWNhdGlvbi94LXd3dy1mb3JtLXVybGVuY29kZWQ7Y2hhcnNldD1VVEYtOCcpXG4gICAgICAgIH1cbiAgICAgIH1cbiAgICB9XG5cbiAgICBpZiAoc3VwcG9ydC5ibG9iKSB7XG4gICAgICB0aGlzLmJsb2IgPSBmdW5jdGlvbigpIHtcbiAgICAgICAgdmFyIHJlamVjdGVkID0gY29uc3VtZWQodGhpcylcbiAgICAgICAgaWYgKHJlamVjdGVkKSB7XG4gICAgICAgICAgcmV0dXJuIHJlamVjdGVkXG4gICAgICAgIH1cblxuICAgICAgICBpZiAodGhpcy5fYm9keUJsb2IpIHtcbiAgICAgICAgICByZXR1cm4gUHJvbWlzZS5yZXNvbHZlKHRoaXMuX2JvZHlCbG9iKVxuICAgICAgICB9IGVsc2UgaWYgKHRoaXMuX2JvZHlBcnJheUJ1ZmZlcikge1xuICAgICAgICAgIHJldHVybiBQcm9taXNlLnJlc29sdmUobmV3IEJsb2IoW3RoaXMuX2JvZHlBcnJheUJ1ZmZlcl0pKVxuICAgICAgICB9IGVsc2UgaWYgKHRoaXMuX2JvZHlGb3JtRGF0YSkge1xuICAgICAgICAgIHRocm93IG5ldyBFcnJvcignY291bGQgbm90IHJlYWQgRm9ybURhdGEgYm9keSBhcyBibG9iJylcbiAgICAgICAgfSBlbHNlIHtcbiAgICAgICAgICByZXR1cm4gUHJvbWlzZS5yZXNvbHZlKG5ldyBCbG9iKFt0aGlzLl9ib2R5VGV4dF0pKVxuICAgICAgICB9XG4gICAgICB9XG4gICAgfVxuXG4gICAgdGhpcy50ZXh0ID0gZnVuY3Rpb24oKSB7XG4gICAgICB2YXIgcmVqZWN0ZWQgPSBjb25zdW1lZCh0aGlzKVxuICAgICAgaWYgKHJlamVjdGVkKSB7XG4gICAgICAgIHJldHVybiByZWplY3RlZFxuICAgICAgfVxuXG4gICAgICBpZiAodGhpcy5fYm9keUJsb2IpIHtcbiAgICAgICAgcmV0dXJuIHJlYWRCbG9iQXNUZXh0KHRoaXMuX2JvZHlCbG9iKVxuICAgICAgfSBlbHNlIGlmICh0aGlzLl9ib2R5QXJyYXlCdWZmZXIpIHtcbiAgICAgICAgdmFyIHZpZXcgPSBuZXcgVWludDhBcnJheSh0aGlzLl9ib2R5QXJyYXlCdWZmZXIpXG4gICAgICAgIHZhciBzdHIgPSBTdHJpbmcuZnJvbUNoYXJDb2RlLmFwcGx5KG51bGwsIHZpZXcpXG4gICAgICAgIHJldHVybiBQcm9taXNlLnJlc29sdmUoc3RyKVxuICAgICAgfSBlbHNlIGlmICh0aGlzLl9ib2R5Rm9ybURhdGEpIHtcbiAgICAgICAgdGhyb3cgbmV3IEVycm9yKCdjb3VsZCBub3QgcmVhZCBGb3JtRGF0YSBib2R5IGFzIHRleHQnKVxuICAgICAgfSBlbHNlIHtcbiAgICAgICAgcmV0dXJuIFByb21pc2UucmVzb2x2ZSh0aGlzLl9ib2R5VGV4dClcbiAgICAgIH1cbiAgICB9XG5cbiAgICBpZiAoc3VwcG9ydC5hcnJheUJ1ZmZlcikge1xuICAgICAgdGhpcy5hcnJheUJ1ZmZlciA9IGZ1bmN0aW9uKCkge1xuICAgICAgICBpZiAodGhpcy5fYm9keUFycmF5QnVmZmVyKSB7XG4gICAgICAgICAgcmV0dXJuIGNvbnN1bWVkKHRoaXMpIHx8IFByb21pc2UucmVzb2x2ZSh0aGlzLl9ib2R5QXJyYXlCdWZmZXIpXG4gICAgICAgIH0gZWxzZSB7XG4gICAgICAgICAgcmV0dXJuIHRoaXMuYmxvYigpLnRoZW4ocmVhZEJsb2JBc0FycmF5QnVmZmVyKVxuICAgICAgICB9XG4gICAgICB9XG4gICAgfVxuXG4gICAgaWYgKHN1cHBvcnQuZm9ybURhdGEpIHtcbiAgICAgIHRoaXMuZm9ybURhdGEgPSBmdW5jdGlvbigpIHtcbiAgICAgICAgcmV0dXJuIHRoaXMudGV4dCgpLnRoZW4oZGVjb2RlKVxuICAgICAgfVxuICAgIH1cblxuICAgIHRoaXMuanNvbiA9IGZ1bmN0aW9uKCkge1xuICAgICAgcmV0dXJuIHRoaXMudGV4dCgpLnRoZW4oSlNPTi5wYXJzZSlcbiAgICB9XG5cbiAgICByZXR1cm4gdGhpc1xuICB9XG5cbiAgLy8gSFRUUCBtZXRob2RzIHdob3NlIGNhcGl0YWxpemF0aW9uIHNob3VsZCBiZSBub3JtYWxpemVkXG4gIHZhciBtZXRob2RzID0gWydERUxFVEUnLCAnR0VUJywgJ0hFQUQnLCAnT1BUSU9OUycsICdQT1NUJywgJ1BVVCddXG5cbiAgZnVuY3Rpb24gbm9ybWFsaXplTWV0aG9kKG1ldGhvZCkge1xuICAgIHZhciB1cGNhc2VkID0gbWV0aG9kLnRvVXBwZXJDYXNlKClcbiAgICByZXR1cm4gKG1ldGhvZHMuaW5kZXhPZih1cGNhc2VkKSA+IC0xKSA/IHVwY2FzZWQgOiBtZXRob2RcbiAgfVxuXG4gIGZ1bmN0aW9uIFJlcXVlc3QoaW5wdXQsIG9wdGlvbnMpIHtcbiAgICBvcHRpb25zID0gb3B0aW9ucyB8fCB7fVxuICAgIHZhciBib2R5ID0gb3B0aW9ucy5ib2R5XG5cbiAgICBpZiAodHlwZW9mIGlucHV0ID09PSAnc3RyaW5nJykge1xuICAgICAgdGhpcy51cmwgPSBpbnB1dFxuICAgIH0gZWxzZSB7XG4gICAgICBpZiAoaW5wdXQuYm9keVVzZWQpIHtcbiAgICAgICAgdGhyb3cgbmV3IFR5cGVFcnJvcignQWxyZWFkeSByZWFkJylcbiAgICAgIH1cbiAgICAgIHRoaXMudXJsID0gaW5wdXQudXJsXG4gICAgICB0aGlzLmNyZWRlbnRpYWxzID0gaW5wdXQuY3JlZGVudGlhbHNcbiAgICAgIGlmICghb3B0aW9ucy5oZWFkZXJzKSB7XG4gICAgICAgIHRoaXMuaGVhZGVycyA9IG5ldyBIZWFkZXJzKGlucHV0LmhlYWRlcnMpXG4gICAgICB9XG4gICAgICB0aGlzLm1ldGhvZCA9IGlucHV0Lm1ldGhvZFxuICAgICAgdGhpcy5tb2RlID0gaW5wdXQubW9kZVxuICAgICAgaWYgKCFib2R5ICYmIGlucHV0Ll9ib2R5SW5pdCAhPSBudWxsKSB7XG4gICAgICAgIGJvZHkgPSBpbnB1dC5fYm9keUluaXRcbiAgICAgICAgaW5wdXQuYm9keVVzZWQgPSB0cnVlXG4gICAgICB9XG4gICAgfVxuXG4gICAgdGhpcy5jcmVkZW50aWFscyA9IG9wdGlvbnMuY3JlZGVudGlhbHMgfHwgdGhpcy5jcmVkZW50aWFscyB8fCAnb21pdCdcbiAgICBpZiAob3B0aW9ucy5oZWFkZXJzIHx8ICF0aGlzLmhlYWRlcnMpIHtcbiAgICAgIHRoaXMuaGVhZGVycyA9IG5ldyBIZWFkZXJzKG9wdGlvbnMuaGVhZGVycylcbiAgICB9XG4gICAgdGhpcy5tZXRob2QgPSBub3JtYWxpemVNZXRob2Qob3B0aW9ucy5tZXRob2QgfHwgdGhpcy5tZXRob2QgfHwgJ0dFVCcpXG4gICAgdGhpcy5tb2RlID0gb3B0aW9ucy5tb2RlIHx8IHRoaXMubW9kZSB8fCBudWxsXG4gICAgdGhpcy5yZWZlcnJlciA9IG51bGxcblxuICAgIGlmICgodGhpcy5tZXRob2QgPT09ICdHRVQnIHx8IHRoaXMubWV0aG9kID09PSAnSEVBRCcpICYmIGJvZHkpIHtcbiAgICAgIHRocm93IG5ldyBUeXBlRXJyb3IoJ0JvZHkgbm90IGFsbG93ZWQgZm9yIEdFVCBvciBIRUFEIHJlcXVlc3RzJylcbiAgICB9XG4gICAgdGhpcy5faW5pdEJvZHkoYm9keSlcbiAgfVxuXG4gIFJlcXVlc3QucHJvdG90eXBlLmNsb25lID0gZnVuY3Rpb24oKSB7XG4gICAgcmV0dXJuIG5ldyBSZXF1ZXN0KHRoaXMsIHsgYm9keTogdGhpcy5fYm9keUluaXQgfSlcbiAgfVxuXG4gIGZ1bmN0aW9uIGRlY29kZShib2R5KSB7XG4gICAgdmFyIGZvcm0gPSBuZXcgRm9ybURhdGEoKVxuICAgIGJvZHkudHJpbSgpLnNwbGl0KCcmJykuZm9yRWFjaChmdW5jdGlvbihieXRlcykge1xuICAgICAgaWYgKGJ5dGVzKSB7XG4gICAgICAgIHZhciBzcGxpdCA9IGJ5dGVzLnNwbGl0KCc9JylcbiAgICAgICAgdmFyIG5hbWUgPSBzcGxpdC5zaGlmdCgpLnJlcGxhY2UoL1xcKy9nLCAnICcpXG4gICAgICAgIHZhciB2YWx1ZSA9IHNwbGl0LmpvaW4oJz0nKS5yZXBsYWNlKC9cXCsvZywgJyAnKVxuICAgICAgICBmb3JtLmFwcGVuZChkZWNvZGVVUklDb21wb25lbnQobmFtZSksIGRlY29kZVVSSUNvbXBvbmVudCh2YWx1ZSkpXG4gICAgICB9XG4gICAgfSlcbiAgICByZXR1cm4gZm9ybVxuICB9XG5cbiAgZnVuY3Rpb24gcGFyc2VIZWFkZXJzKHJhd0hlYWRlcnMpIHtcbiAgICB2YXIgaGVhZGVycyA9IG5ldyBIZWFkZXJzKClcbiAgICByYXdIZWFkZXJzLnNwbGl0KCdcXHJcXG4nKS5mb3JFYWNoKGZ1bmN0aW9uKGxpbmUpIHtcbiAgICAgIHZhciBwYXJ0cyA9IGxpbmUuc3BsaXQoJzonKVxuICAgICAgdmFyIGtleSA9IHBhcnRzLnNoaWZ0KCkudHJpbSgpXG4gICAgICBpZiAoa2V5KSB7XG4gICAgICAgIHZhciB2YWx1ZSA9IHBhcnRzLmpvaW4oJzonKS50cmltKClcbiAgICAgICAgaGVhZGVycy5hcHBlbmQoa2V5LCB2YWx1ZSlcbiAgICAgIH1cbiAgICB9KVxuICAgIHJldHVybiBoZWFkZXJzXG4gIH1cblxuICBCb2R5LmNhbGwoUmVxdWVzdC5wcm90b3R5cGUpXG5cbiAgZnVuY3Rpb24gUmVzcG9uc2UoYm9keUluaXQsIG9wdGlvbnMpIHtcbiAgICBpZiAoIW9wdGlvbnMpIHtcbiAgICAgIG9wdGlvbnMgPSB7fVxuICAgIH1cblxuICAgIHRoaXMudHlwZSA9ICdkZWZhdWx0J1xuICAgIHRoaXMuc3RhdHVzID0gJ3N0YXR1cycgaW4gb3B0aW9ucyA/IG9wdGlvbnMuc3RhdHVzIDogMjAwXG4gICAgdGhpcy5vayA9IHRoaXMuc3RhdHVzID49IDIwMCAmJiB0aGlzLnN0YXR1cyA8IDMwMFxuICAgIHRoaXMuc3RhdHVzVGV4dCA9ICdzdGF0dXNUZXh0JyBpbiBvcHRpb25zID8gb3B0aW9ucy5zdGF0dXNUZXh0IDogJ09LJ1xuICAgIHRoaXMuaGVhZGVycyA9IG5ldyBIZWFkZXJzKG9wdGlvbnMuaGVhZGVycylcbiAgICB0aGlzLnVybCA9IG9wdGlvbnMudXJsIHx8ICcnXG4gICAgdGhpcy5faW5pdEJvZHkoYm9keUluaXQpXG4gIH1cblxuICBCb2R5LmNhbGwoUmVzcG9uc2UucHJvdG90eXBlKVxuXG4gIFJlc3BvbnNlLnByb3RvdHlwZS5jbG9uZSA9IGZ1bmN0aW9uKCkge1xuICAgIHJldHVybiBuZXcgUmVzcG9uc2UodGhpcy5fYm9keUluaXQsIHtcbiAgICAgIHN0YXR1czogdGhpcy5zdGF0dXMsXG4gICAgICBzdGF0dXNUZXh0OiB0aGlzLnN0YXR1c1RleHQsXG4gICAgICBoZWFkZXJzOiBuZXcgSGVhZGVycyh0aGlzLmhlYWRlcnMpLFxuICAgICAgdXJsOiB0aGlzLnVybFxuICAgIH0pXG4gIH1cblxuICBSZXNwb25zZS5lcnJvciA9IGZ1bmN0aW9uKCkge1xuICAgIHZhciByZXNwb25zZSA9IG5ldyBSZXNwb25zZShudWxsLCB7c3RhdHVzOiAwLCBzdGF0dXNUZXh0OiAnJ30pXG4gICAgcmVzcG9uc2UudHlwZSA9ICdlcnJvcidcbiAgICByZXR1cm4gcmVzcG9uc2VcbiAgfVxuXG4gIHZhciByZWRpcmVjdFN0YXR1c2VzID0gWzMwMSwgMzAyLCAzMDMsIDMwNywgMzA4XVxuXG4gIFJlc3BvbnNlLnJlZGlyZWN0ID0gZnVuY3Rpb24odXJsLCBzdGF0dXMpIHtcbiAgICBpZiAocmVkaXJlY3RTdGF0dXNlcy5pbmRleE9mKHN0YXR1cykgPT09IC0xKSB7XG4gICAgICB0aHJvdyBuZXcgUmFuZ2VFcnJvcignSW52YWxpZCBzdGF0dXMgY29kZScpXG4gICAgfVxuXG4gICAgcmV0dXJuIG5ldyBSZXNwb25zZShudWxsLCB7c3RhdHVzOiBzdGF0dXMsIGhlYWRlcnM6IHtsb2NhdGlvbjogdXJsfX0pXG4gIH1cblxuICBzZWxmLkhlYWRlcnMgPSBIZWFkZXJzXG4gIHNlbGYuUmVxdWVzdCA9IFJlcXVlc3RcbiAgc2VsZi5SZXNwb25zZSA9IFJlc3BvbnNlXG5cbiAgc2VsZi5mZXRjaCA9IGZ1bmN0aW9uKGlucHV0LCBpbml0KSB7XG4gICAgcmV0dXJuIG5ldyBQcm9taXNlKGZ1bmN0aW9uKHJlc29sdmUsIHJlamVjdCkge1xuICAgICAgdmFyIHJlcXVlc3QgPSBuZXcgUmVxdWVzdChpbnB1dCwgaW5pdClcbiAgICAgIHZhciB4aHIgPSBuZXcgWE1MSHR0cFJlcXVlc3QoKVxuXG4gICAgICB4aHIub25sb2FkID0gZnVuY3Rpb24oKSB7XG4gICAgICAgIHZhciBvcHRpb25zID0ge1xuICAgICAgICAgIHN0YXR1czogeGhyLnN0YXR1cyxcbiAgICAgICAgICBzdGF0dXNUZXh0OiB4aHIuc3RhdHVzVGV4dCxcbiAgICAgICAgICBoZWFkZXJzOiBwYXJzZUhlYWRlcnMoeGhyLmdldEFsbFJlc3BvbnNlSGVhZGVycygpIHx8ICcnKVxuICAgICAgICB9XG4gICAgICAgIG9wdGlvbnMudXJsID0gJ3Jlc3BvbnNlVVJMJyBpbiB4aHIgPyB4aHIucmVzcG9uc2VVUkwgOiBvcHRpb25zLmhlYWRlcnMuZ2V0KCdYLVJlcXVlc3QtVVJMJylcbiAgICAgICAgdmFyIGJvZHkgPSAncmVzcG9uc2UnIGluIHhociA/IHhoci5yZXNwb25zZSA6IHhoci5yZXNwb25zZVRleHRcbiAgICAgICAgcmVzb2x2ZShuZXcgUmVzcG9uc2UoYm9keSwgb3B0aW9ucykpXG4gICAgICB9XG5cbiAgICAgIHhoci5vbmVycm9yID0gZnVuY3Rpb24oKSB7XG4gICAgICAgIHJlamVjdChuZXcgVHlwZUVycm9yKCdOZXR3b3JrIHJlcXVlc3QgZmFpbGVkJykpXG4gICAgICB9XG5cbiAgICAgIHhoci5vbnRpbWVvdXQgPSBmdW5jdGlvbigpIHtcbiAgICAgICAgcmVqZWN0KG5ldyBUeXBlRXJyb3IoJ05ldHdvcmsgcmVxdWVzdCBmYWlsZWQnKSlcbiAgICAgIH1cblxuICAgICAgeGhyLm9wZW4ocmVxdWVzdC5tZXRob2QsIHJlcXVlc3QudXJsLCB0cnVlKVxuXG4gICAgICBpZiAocmVxdWVzdC5jcmVkZW50aWFscyA9PT0gJ2luY2x1ZGUnKSB7XG4gICAgICAgIHhoci53aXRoQ3JlZGVudGlhbHMgPSB0cnVlXG4gICAgICB9XG5cbiAgICAgIGlmICgncmVzcG9uc2VUeXBlJyBpbiB4aHIgJiYgc3VwcG9ydC5ibG9iKSB7XG4gICAgICAgIHhoci5yZXNwb25zZVR5cGUgPSAnYmxvYidcbiAgICAgIH1cblxuICAgICAgcmVxdWVzdC5oZWFkZXJzLmZvckVhY2goZnVuY3Rpb24odmFsdWUsIG5hbWUpIHtcbiAgICAgICAgeGhyLnNldFJlcXVlc3RIZWFkZXIobmFtZSwgdmFsdWUpXG4gICAgICB9KVxuXG4gICAgICB4aHIuc2VuZCh0eXBlb2YgcmVxdWVzdC5fYm9keUluaXQgPT09ICd1bmRlZmluZWQnID8gbnVsbCA6IHJlcXVlc3QuX2JvZHlJbml0KVxuICAgIH0pXG4gIH1cbiAgc2VsZi5mZXRjaC5wb2x5ZmlsbCA9IHRydWVcbn0pKHR5cGVvZiBzZWxmICE9PSAndW5kZWZpbmVkJyA/IHNlbGYgOiB0aGlzKTtcbiJdfQ== \ No newline at end of file diff --git a/rest_framework/static/rest_framework/js/csrf.js b/rest_framework/static/rest_framework/js/csrf.js index 97c8d01242..6e4bf39a79 100644 --- a/rest_framework/static/rest_framework/js/csrf.js +++ b/rest_framework/static/rest_framework/js/csrf.js @@ -38,7 +38,7 @@ function sameOrigin(url) { !(/^(\/\/|http:|https:).*/.test(url)); } -var csrftoken = getCookie(window.drf.csrfCookieName); +var csrftoken = window.drf.csrfToken; $.ajaxSetup({ beforeSend: function(xhr, settings) { diff --git a/rest_framework/static/rest_framework/js/default.js b/rest_framework/static/rest_framework/js/default.js index d8394b0bf5..bec2e4f9eb 100644 --- a/rest_framework/static/rest_framework/js/default.js +++ b/rest_framework/static/rest_framework/js/default.js @@ -41,7 +41,7 @@ $(document).ready(function() { $('.form-switcher a:first').tab('show'); } - $(window).load(function() { + $(window).on('load', function() { $('#errorModal').modal('show'); }); }); diff --git a/rest_framework/static/rest_framework/js/jquery-1.12.4.min.js b/rest_framework/static/rest_framework/js/jquery-1.12.4.min.js deleted file mode 100644 index e836475870..0000000000 --- a/rest_framework/static/rest_framework/js/jquery-1.12.4.min.js +++ /dev/null @@ -1,5 +0,0 @@ -/*! jQuery v1.12.4 | (c) jQuery Foundation | jquery.org/license */ -!function(a,b){"object"==typeof module&&"object"==typeof module.exports?module.exports=a.document?b(a,!0):function(a){if(!a.document)throw new Error("jQuery requires a window with a document");return b(a)}:b(a)}("undefined"!=typeof window?window:this,function(a,b){var c=[],d=a.document,e=c.slice,f=c.concat,g=c.push,h=c.indexOf,i={},j=i.toString,k=i.hasOwnProperty,l={},m="1.12.4",n=function(a,b){return new n.fn.init(a,b)},o=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g,p=/^-ms-/,q=/-([\da-z])/gi,r=function(a,b){return b.toUpperCase()};n.fn=n.prototype={jquery:m,constructor:n,selector:"",length:0,toArray:function(){return e.call(this)},get:function(a){return null!=a?0>a?this[a+this.length]:this[a]:e.call(this)},pushStack:function(a){var b=n.merge(this.constructor(),a);return b.prevObject=this,b.context=this.context,b},each:function(a){return n.each(this,a)},map:function(a){return this.pushStack(n.map(this,function(b,c){return a.call(b,c,b)}))},slice:function(){return this.pushStack(e.apply(this,arguments))},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},eq:function(a){var b=this.length,c=+a+(0>a?b:0);return this.pushStack(c>=0&&b>c?[this[c]]:[])},end:function(){return this.prevObject||this.constructor()},push:g,sort:c.sort,splice:c.splice},n.extend=n.fn.extend=function(){var a,b,c,d,e,f,g=arguments[0]||{},h=1,i=arguments.length,j=!1;for("boolean"==typeof g&&(j=g,g=arguments[h]||{},h++),"object"==typeof g||n.isFunction(g)||(g={}),h===i&&(g=this,h--);i>h;h++)if(null!=(e=arguments[h]))for(d in e)a=g[d],c=e[d],g!==c&&(j&&c&&(n.isPlainObject(c)||(b=n.isArray(c)))?(b?(b=!1,f=a&&n.isArray(a)?a:[]):f=a&&n.isPlainObject(a)?a:{},g[d]=n.extend(j,f,c)):void 0!==c&&(g[d]=c));return g},n.extend({expando:"jQuery"+(m+Math.random()).replace(/\D/g,""),isReady:!0,error:function(a){throw new Error(a)},noop:function(){},isFunction:function(a){return"function"===n.type(a)},isArray:Array.isArray||function(a){return"array"===n.type(a)},isWindow:function(a){return null!=a&&a==a.window},isNumeric:function(a){var b=a&&a.toString();return!n.isArray(a)&&b-parseFloat(b)+1>=0},isEmptyObject:function(a){var b;for(b in a)return!1;return!0},isPlainObject:function(a){var b;if(!a||"object"!==n.type(a)||a.nodeType||n.isWindow(a))return!1;try{if(a.constructor&&!k.call(a,"constructor")&&!k.call(a.constructor.prototype,"isPrototypeOf"))return!1}catch(c){return!1}if(!l.ownFirst)for(b in a)return k.call(a,b);for(b in a);return void 0===b||k.call(a,b)},type:function(a){return null==a?a+"":"object"==typeof a||"function"==typeof a?i[j.call(a)]||"object":typeof a},globalEval:function(b){b&&n.trim(b)&&(a.execScript||function(b){a.eval.call(a,b)})(b)},camelCase:function(a){return a.replace(p,"ms-").replace(q,r)},nodeName:function(a,b){return a.nodeName&&a.nodeName.toLowerCase()===b.toLowerCase()},each:function(a,b){var c,d=0;if(s(a)){for(c=a.length;c>d;d++)if(b.call(a[d],d,a[d])===!1)break}else for(d in a)if(b.call(a[d],d,a[d])===!1)break;return a},trim:function(a){return null==a?"":(a+"").replace(o,"")},makeArray:function(a,b){var c=b||[];return null!=a&&(s(Object(a))?n.merge(c,"string"==typeof a?[a]:a):g.call(c,a)),c},inArray:function(a,b,c){var d;if(b){if(h)return h.call(b,a,c);for(d=b.length,c=c?0>c?Math.max(0,d+c):c:0;d>c;c++)if(c in b&&b[c]===a)return c}return-1},merge:function(a,b){var c=+b.length,d=0,e=a.length;while(c>d)a[e++]=b[d++];if(c!==c)while(void 0!==b[d])a[e++]=b[d++];return a.length=e,a},grep:function(a,b,c){for(var d,e=[],f=0,g=a.length,h=!c;g>f;f++)d=!b(a[f],f),d!==h&&e.push(a[f]);return e},map:function(a,b,c){var d,e,g=0,h=[];if(s(a))for(d=a.length;d>g;g++)e=b(a[g],g,c),null!=e&&h.push(e);else for(g in a)e=b(a[g],g,c),null!=e&&h.push(e);return f.apply([],h)},guid:1,proxy:function(a,b){var c,d,f;return"string"==typeof b&&(f=a[b],b=a,a=f),n.isFunction(a)?(c=e.call(arguments,2),d=function(){return a.apply(b||this,c.concat(e.call(arguments)))},d.guid=a.guid=a.guid||n.guid++,d):void 0},now:function(){return+new Date},support:l}),"function"==typeof Symbol&&(n.fn[Symbol.iterator]=c[Symbol.iterator]),n.each("Boolean Number String Function Array Date RegExp Object Error Symbol".split(" "),function(a,b){i["[object "+b+"]"]=b.toLowerCase()});function s(a){var b=!!a&&"length"in a&&a.length,c=n.type(a);return"function"===c||n.isWindow(a)?!1:"array"===c||0===b||"number"==typeof b&&b>0&&b-1 in a}var t=function(a){var b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u="sizzle"+1*new Date,v=a.document,w=0,x=0,y=ga(),z=ga(),A=ga(),B=function(a,b){return a===b&&(l=!0),0},C=1<<31,D={}.hasOwnProperty,E=[],F=E.pop,G=E.push,H=E.push,I=E.slice,J=function(a,b){for(var c=0,d=a.length;d>c;c++)if(a[c]===b)return c;return-1},K="checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",L="[\\x20\\t\\r\\n\\f]",M="(?:\\\\.|[\\w-]|[^\\x00-\\xa0])+",N="\\["+L+"*("+M+")(?:"+L+"*([*^$|!~]?=)"+L+"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|("+M+"))|)"+L+"*\\]",O=":("+M+")(?:\\((('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|((?:\\\\.|[^\\\\()[\\]]|"+N+")*)|.*)\\)|)",P=new RegExp(L+"+","g"),Q=new RegExp("^"+L+"+|((?:^|[^\\\\])(?:\\\\.)*)"+L+"+$","g"),R=new RegExp("^"+L+"*,"+L+"*"),S=new RegExp("^"+L+"*([>+~]|"+L+")"+L+"*"),T=new RegExp("="+L+"*([^\\]'\"]*?)"+L+"*\\]","g"),U=new RegExp(O),V=new RegExp("^"+M+"$"),W={ID:new RegExp("^#("+M+")"),CLASS:new RegExp("^\\.("+M+")"),TAG:new RegExp("^("+M+"|[*])"),ATTR:new RegExp("^"+N),PSEUDO:new RegExp("^"+O),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+L+"*(even|odd|(([+-]|)(\\d*)n|)"+L+"*(?:([+-]|)"+L+"*(\\d+)|))"+L+"*\\)|)","i"),bool:new RegExp("^(?:"+K+")$","i"),needsContext:new RegExp("^"+L+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+L+"*((?:-\\d)?\\d*)"+L+"*\\)|)(?=[^-]|$)","i")},X=/^(?:input|select|textarea|button)$/i,Y=/^h\d$/i,Z=/^[^{]+\{\s*\[native \w/,$=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,_=/[+~]/,aa=/'|\\/g,ba=new RegExp("\\\\([\\da-f]{1,6}"+L+"?|("+L+")|.)","ig"),ca=function(a,b,c){var d="0x"+b-65536;return d!==d||c?b:0>d?String.fromCharCode(d+65536):String.fromCharCode(d>>10|55296,1023&d|56320)},da=function(){m()};try{H.apply(E=I.call(v.childNodes),v.childNodes),E[v.childNodes.length].nodeType}catch(ea){H={apply:E.length?function(a,b){G.apply(a,I.call(b))}:function(a,b){var c=a.length,d=0;while(a[c++]=b[d++]);a.length=c-1}}}function fa(a,b,d,e){var f,h,j,k,l,o,r,s,w=b&&b.ownerDocument,x=b?b.nodeType:9;if(d=d||[],"string"!=typeof a||!a||1!==x&&9!==x&&11!==x)return d;if(!e&&((b?b.ownerDocument||b:v)!==n&&m(b),b=b||n,p)){if(11!==x&&(o=$.exec(a)))if(f=o[1]){if(9===x){if(!(j=b.getElementById(f)))return d;if(j.id===f)return d.push(j),d}else if(w&&(j=w.getElementById(f))&&t(b,j)&&j.id===f)return d.push(j),d}else{if(o[2])return H.apply(d,b.getElementsByTagName(a)),d;if((f=o[3])&&c.getElementsByClassName&&b.getElementsByClassName)return H.apply(d,b.getElementsByClassName(f)),d}if(c.qsa&&!A[a+" "]&&(!q||!q.test(a))){if(1!==x)w=b,s=a;else if("object"!==b.nodeName.toLowerCase()){(k=b.getAttribute("id"))?k=k.replace(aa,"\\$&"):b.setAttribute("id",k=u),r=g(a),h=r.length,l=V.test(k)?"#"+k:"[id='"+k+"']";while(h--)r[h]=l+" "+qa(r[h]);s=r.join(","),w=_.test(a)&&oa(b.parentNode)||b}if(s)try{return H.apply(d,w.querySelectorAll(s)),d}catch(y){}finally{k===u&&b.removeAttribute("id")}}}return i(a.replace(Q,"$1"),b,d,e)}function ga(){var a=[];function b(c,e){return a.push(c+" ")>d.cacheLength&&delete b[a.shift()],b[c+" "]=e}return b}function ha(a){return a[u]=!0,a}function ia(a){var b=n.createElement("div");try{return!!a(b)}catch(c){return!1}finally{b.parentNode&&b.parentNode.removeChild(b),b=null}}function ja(a,b){var c=a.split("|"),e=c.length;while(e--)d.attrHandle[c[e]]=b}function ka(a,b){var c=b&&a,d=c&&1===a.nodeType&&1===b.nodeType&&(~b.sourceIndex||C)-(~a.sourceIndex||C);if(d)return d;if(c)while(c=c.nextSibling)if(c===b)return-1;return a?1:-1}function la(a){return function(b){var c=b.nodeName.toLowerCase();return"input"===c&&b.type===a}}function ma(a){return function(b){var c=b.nodeName.toLowerCase();return("input"===c||"button"===c)&&b.type===a}}function na(a){return ha(function(b){return b=+b,ha(function(c,d){var e,f=a([],c.length,b),g=f.length;while(g--)c[e=f[g]]&&(c[e]=!(d[e]=c[e]))})})}function oa(a){return a&&"undefined"!=typeof a.getElementsByTagName&&a}c=fa.support={},f=fa.isXML=function(a){var b=a&&(a.ownerDocument||a).documentElement;return b?"HTML"!==b.nodeName:!1},m=fa.setDocument=function(a){var b,e,g=a?a.ownerDocument||a:v;return g!==n&&9===g.nodeType&&g.documentElement?(n=g,o=n.documentElement,p=!f(n),(e=n.defaultView)&&e.top!==e&&(e.addEventListener?e.addEventListener("unload",da,!1):e.attachEvent&&e.attachEvent("onunload",da)),c.attributes=ia(function(a){return a.className="i",!a.getAttribute("className")}),c.getElementsByTagName=ia(function(a){return a.appendChild(n.createComment("")),!a.getElementsByTagName("*").length}),c.getElementsByClassName=Z.test(n.getElementsByClassName),c.getById=ia(function(a){return o.appendChild(a).id=u,!n.getElementsByName||!n.getElementsByName(u).length}),c.getById?(d.find.ID=function(a,b){if("undefined"!=typeof b.getElementById&&p){var c=b.getElementById(a);return c?[c]:[]}},d.filter.ID=function(a){var b=a.replace(ba,ca);return function(a){return a.getAttribute("id")===b}}):(delete d.find.ID,d.filter.ID=function(a){var b=a.replace(ba,ca);return function(a){var c="undefined"!=typeof a.getAttributeNode&&a.getAttributeNode("id");return c&&c.value===b}}),d.find.TAG=c.getElementsByTagName?function(a,b){return"undefined"!=typeof b.getElementsByTagName?b.getElementsByTagName(a):c.qsa?b.querySelectorAll(a):void 0}:function(a,b){var c,d=[],e=0,f=b.getElementsByTagName(a);if("*"===a){while(c=f[e++])1===c.nodeType&&d.push(c);return d}return f},d.find.CLASS=c.getElementsByClassName&&function(a,b){return"undefined"!=typeof b.getElementsByClassName&&p?b.getElementsByClassName(a):void 0},r=[],q=[],(c.qsa=Z.test(n.querySelectorAll))&&(ia(function(a){o.appendChild(a).innerHTML="",a.querySelectorAll("[msallowcapture^='']").length&&q.push("[*^$]="+L+"*(?:''|\"\")"),a.querySelectorAll("[selected]").length||q.push("\\["+L+"*(?:value|"+K+")"),a.querySelectorAll("[id~="+u+"-]").length||q.push("~="),a.querySelectorAll(":checked").length||q.push(":checked"),a.querySelectorAll("a#"+u+"+*").length||q.push(".#.+[+~]")}),ia(function(a){var b=n.createElement("input");b.setAttribute("type","hidden"),a.appendChild(b).setAttribute("name","D"),a.querySelectorAll("[name=d]").length&&q.push("name"+L+"*[*^$|!~]?="),a.querySelectorAll(":enabled").length||q.push(":enabled",":disabled"),a.querySelectorAll("*,:x"),q.push(",.*:")})),(c.matchesSelector=Z.test(s=o.matches||o.webkitMatchesSelector||o.mozMatchesSelector||o.oMatchesSelector||o.msMatchesSelector))&&ia(function(a){c.disconnectedMatch=s.call(a,"div"),s.call(a,"[s!='']:x"),r.push("!=",O)}),q=q.length&&new RegExp(q.join("|")),r=r.length&&new RegExp(r.join("|")),b=Z.test(o.compareDocumentPosition),t=b||Z.test(o.contains)?function(a,b){var c=9===a.nodeType?a.documentElement:a,d=b&&b.parentNode;return a===d||!(!d||1!==d.nodeType||!(c.contains?c.contains(d):a.compareDocumentPosition&&16&a.compareDocumentPosition(d)))}:function(a,b){if(b)while(b=b.parentNode)if(b===a)return!0;return!1},B=b?function(a,b){if(a===b)return l=!0,0;var d=!a.compareDocumentPosition-!b.compareDocumentPosition;return d?d:(d=(a.ownerDocument||a)===(b.ownerDocument||b)?a.compareDocumentPosition(b):1,1&d||!c.sortDetached&&b.compareDocumentPosition(a)===d?a===n||a.ownerDocument===v&&t(v,a)?-1:b===n||b.ownerDocument===v&&t(v,b)?1:k?J(k,a)-J(k,b):0:4&d?-1:1)}:function(a,b){if(a===b)return l=!0,0;var c,d=0,e=a.parentNode,f=b.parentNode,g=[a],h=[b];if(!e||!f)return a===n?-1:b===n?1:e?-1:f?1:k?J(k,a)-J(k,b):0;if(e===f)return ka(a,b);c=a;while(c=c.parentNode)g.unshift(c);c=b;while(c=c.parentNode)h.unshift(c);while(g[d]===h[d])d++;return d?ka(g[d],h[d]):g[d]===v?-1:h[d]===v?1:0},n):n},fa.matches=function(a,b){return fa(a,null,null,b)},fa.matchesSelector=function(a,b){if((a.ownerDocument||a)!==n&&m(a),b=b.replace(T,"='$1']"),c.matchesSelector&&p&&!A[b+" "]&&(!r||!r.test(b))&&(!q||!q.test(b)))try{var d=s.call(a,b);if(d||c.disconnectedMatch||a.document&&11!==a.document.nodeType)return d}catch(e){}return fa(b,n,null,[a]).length>0},fa.contains=function(a,b){return(a.ownerDocument||a)!==n&&m(a),t(a,b)},fa.attr=function(a,b){(a.ownerDocument||a)!==n&&m(a);var e=d.attrHandle[b.toLowerCase()],f=e&&D.call(d.attrHandle,b.toLowerCase())?e(a,b,!p):void 0;return void 0!==f?f:c.attributes||!p?a.getAttribute(b):(f=a.getAttributeNode(b))&&f.specified?f.value:null},fa.error=function(a){throw new Error("Syntax error, unrecognized expression: "+a)},fa.uniqueSort=function(a){var b,d=[],e=0,f=0;if(l=!c.detectDuplicates,k=!c.sortStable&&a.slice(0),a.sort(B),l){while(b=a[f++])b===a[f]&&(e=d.push(f));while(e--)a.splice(d[e],1)}return k=null,a},e=fa.getText=function(a){var b,c="",d=0,f=a.nodeType;if(f){if(1===f||9===f||11===f){if("string"==typeof a.textContent)return a.textContent;for(a=a.firstChild;a;a=a.nextSibling)c+=e(a)}else if(3===f||4===f)return a.nodeValue}else while(b=a[d++])c+=e(b);return c},d=fa.selectors={cacheLength:50,createPseudo:ha,match:W,attrHandle:{},find:{},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(a){return a[1]=a[1].replace(ba,ca),a[3]=(a[3]||a[4]||a[5]||"").replace(ba,ca),"~="===a[2]&&(a[3]=" "+a[3]+" "),a.slice(0,4)},CHILD:function(a){return a[1]=a[1].toLowerCase(),"nth"===a[1].slice(0,3)?(a[3]||fa.error(a[0]),a[4]=+(a[4]?a[5]+(a[6]||1):2*("even"===a[3]||"odd"===a[3])),a[5]=+(a[7]+a[8]||"odd"===a[3])):a[3]&&fa.error(a[0]),a},PSEUDO:function(a){var b,c=!a[6]&&a[2];return W.CHILD.test(a[0])?null:(a[3]?a[2]=a[4]||a[5]||"":c&&U.test(c)&&(b=g(c,!0))&&(b=c.indexOf(")",c.length-b)-c.length)&&(a[0]=a[0].slice(0,b),a[2]=c.slice(0,b)),a.slice(0,3))}},filter:{TAG:function(a){var b=a.replace(ba,ca).toLowerCase();return"*"===a?function(){return!0}:function(a){return a.nodeName&&a.nodeName.toLowerCase()===b}},CLASS:function(a){var b=y[a+" "];return b||(b=new RegExp("(^|"+L+")"+a+"("+L+"|$)"))&&y(a,function(a){return b.test("string"==typeof a.className&&a.className||"undefined"!=typeof a.getAttribute&&a.getAttribute("class")||"")})},ATTR:function(a,b,c){return function(d){var e=fa.attr(d,a);return null==e?"!="===b:b?(e+="","="===b?e===c:"!="===b?e!==c:"^="===b?c&&0===e.indexOf(c):"*="===b?c&&e.indexOf(c)>-1:"$="===b?c&&e.slice(-c.length)===c:"~="===b?(" "+e.replace(P," ")+" ").indexOf(c)>-1:"|="===b?e===c||e.slice(0,c.length+1)===c+"-":!1):!0}},CHILD:function(a,b,c,d,e){var f="nth"!==a.slice(0,3),g="last"!==a.slice(-4),h="of-type"===b;return 1===d&&0===e?function(a){return!!a.parentNode}:function(b,c,i){var j,k,l,m,n,o,p=f!==g?"nextSibling":"previousSibling",q=b.parentNode,r=h&&b.nodeName.toLowerCase(),s=!i&&!h,t=!1;if(q){if(f){while(p){m=b;while(m=m[p])if(h?m.nodeName.toLowerCase()===r:1===m.nodeType)return!1;o=p="only"===a&&!o&&"nextSibling"}return!0}if(o=[g?q.firstChild:q.lastChild],g&&s){m=q,l=m[u]||(m[u]={}),k=l[m.uniqueID]||(l[m.uniqueID]={}),j=k[a]||[],n=j[0]===w&&j[1],t=n&&j[2],m=n&&q.childNodes[n];while(m=++n&&m&&m[p]||(t=n=0)||o.pop())if(1===m.nodeType&&++t&&m===b){k[a]=[w,n,t];break}}else if(s&&(m=b,l=m[u]||(m[u]={}),k=l[m.uniqueID]||(l[m.uniqueID]={}),j=k[a]||[],n=j[0]===w&&j[1],t=n),t===!1)while(m=++n&&m&&m[p]||(t=n=0)||o.pop())if((h?m.nodeName.toLowerCase()===r:1===m.nodeType)&&++t&&(s&&(l=m[u]||(m[u]={}),k=l[m.uniqueID]||(l[m.uniqueID]={}),k[a]=[w,t]),m===b))break;return t-=e,t===d||t%d===0&&t/d>=0}}},PSEUDO:function(a,b){var c,e=d.pseudos[a]||d.setFilters[a.toLowerCase()]||fa.error("unsupported pseudo: "+a);return e[u]?e(b):e.length>1?(c=[a,a,"",b],d.setFilters.hasOwnProperty(a.toLowerCase())?ha(function(a,c){var d,f=e(a,b),g=f.length;while(g--)d=J(a,f[g]),a[d]=!(c[d]=f[g])}):function(a){return e(a,0,c)}):e}},pseudos:{not:ha(function(a){var b=[],c=[],d=h(a.replace(Q,"$1"));return d[u]?ha(function(a,b,c,e){var f,g=d(a,null,e,[]),h=a.length;while(h--)(f=g[h])&&(a[h]=!(b[h]=f))}):function(a,e,f){return b[0]=a,d(b,null,f,c),b[0]=null,!c.pop()}}),has:ha(function(a){return function(b){return fa(a,b).length>0}}),contains:ha(function(a){return a=a.replace(ba,ca),function(b){return(b.textContent||b.innerText||e(b)).indexOf(a)>-1}}),lang:ha(function(a){return V.test(a||"")||fa.error("unsupported lang: "+a),a=a.replace(ba,ca).toLowerCase(),function(b){var c;do if(c=p?b.lang:b.getAttribute("xml:lang")||b.getAttribute("lang"))return c=c.toLowerCase(),c===a||0===c.indexOf(a+"-");while((b=b.parentNode)&&1===b.nodeType);return!1}}),target:function(b){var c=a.location&&a.location.hash;return c&&c.slice(1)===b.id},root:function(a){return a===o},focus:function(a){return a===n.activeElement&&(!n.hasFocus||n.hasFocus())&&!!(a.type||a.href||~a.tabIndex)},enabled:function(a){return a.disabled===!1},disabled:function(a){return a.disabled===!0},checked:function(a){var b=a.nodeName.toLowerCase();return"input"===b&&!!a.checked||"option"===b&&!!a.selected},selected:function(a){return a.parentNode&&a.parentNode.selectedIndex,a.selected===!0},empty:function(a){for(a=a.firstChild;a;a=a.nextSibling)if(a.nodeType<6)return!1;return!0},parent:function(a){return!d.pseudos.empty(a)},header:function(a){return Y.test(a.nodeName)},input:function(a){return X.test(a.nodeName)},button:function(a){var b=a.nodeName.toLowerCase();return"input"===b&&"button"===a.type||"button"===b},text:function(a){var b;return"input"===a.nodeName.toLowerCase()&&"text"===a.type&&(null==(b=a.getAttribute("type"))||"text"===b.toLowerCase())},first:na(function(){return[0]}),last:na(function(a,b){return[b-1]}),eq:na(function(a,b,c){return[0>c?c+b:c]}),even:na(function(a,b){for(var c=0;b>c;c+=2)a.push(c);return a}),odd:na(function(a,b){for(var c=1;b>c;c+=2)a.push(c);return a}),lt:na(function(a,b,c){for(var d=0>c?c+b:c;--d>=0;)a.push(d);return a}),gt:na(function(a,b,c){for(var d=0>c?c+b:c;++db;b++)d+=a[b].value;return d}function ra(a,b,c){var d=b.dir,e=c&&"parentNode"===d,f=x++;return b.first?function(b,c,f){while(b=b[d])if(1===b.nodeType||e)return a(b,c,f)}:function(b,c,g){var h,i,j,k=[w,f];if(g){while(b=b[d])if((1===b.nodeType||e)&&a(b,c,g))return!0}else while(b=b[d])if(1===b.nodeType||e){if(j=b[u]||(b[u]={}),i=j[b.uniqueID]||(j[b.uniqueID]={}),(h=i[d])&&h[0]===w&&h[1]===f)return k[2]=h[2];if(i[d]=k,k[2]=a(b,c,g))return!0}}}function sa(a){return a.length>1?function(b,c,d){var e=a.length;while(e--)if(!a[e](b,c,d))return!1;return!0}:a[0]}function ta(a,b,c){for(var d=0,e=b.length;e>d;d++)fa(a,b[d],c);return c}function ua(a,b,c,d,e){for(var f,g=[],h=0,i=a.length,j=null!=b;i>h;h++)(f=a[h])&&(c&&!c(f,d,e)||(g.push(f),j&&b.push(h)));return g}function va(a,b,c,d,e,f){return d&&!d[u]&&(d=va(d)),e&&!e[u]&&(e=va(e,f)),ha(function(f,g,h,i){var j,k,l,m=[],n=[],o=g.length,p=f||ta(b||"*",h.nodeType?[h]:h,[]),q=!a||!f&&b?p:ua(p,m,a,h,i),r=c?e||(f?a:o||d)?[]:g:q;if(c&&c(q,r,h,i),d){j=ua(r,n),d(j,[],h,i),k=j.length;while(k--)(l=j[k])&&(r[n[k]]=!(q[n[k]]=l))}if(f){if(e||a){if(e){j=[],k=r.length;while(k--)(l=r[k])&&j.push(q[k]=l);e(null,r=[],j,i)}k=r.length;while(k--)(l=r[k])&&(j=e?J(f,l):m[k])>-1&&(f[j]=!(g[j]=l))}}else r=ua(r===g?r.splice(o,r.length):r),e?e(null,g,r,i):H.apply(g,r)})}function wa(a){for(var b,c,e,f=a.length,g=d.relative[a[0].type],h=g||d.relative[" "],i=g?1:0,k=ra(function(a){return a===b},h,!0),l=ra(function(a){return J(b,a)>-1},h,!0),m=[function(a,c,d){var e=!g&&(d||c!==j)||((b=c).nodeType?k(a,c,d):l(a,c,d));return b=null,e}];f>i;i++)if(c=d.relative[a[i].type])m=[ra(sa(m),c)];else{if(c=d.filter[a[i].type].apply(null,a[i].matches),c[u]){for(e=++i;f>e;e++)if(d.relative[a[e].type])break;return va(i>1&&sa(m),i>1&&qa(a.slice(0,i-1).concat({value:" "===a[i-2].type?"*":""})).replace(Q,"$1"),c,e>i&&wa(a.slice(i,e)),f>e&&wa(a=a.slice(e)),f>e&&qa(a))}m.push(c)}return sa(m)}function xa(a,b){var c=b.length>0,e=a.length>0,f=function(f,g,h,i,k){var l,o,q,r=0,s="0",t=f&&[],u=[],v=j,x=f||e&&d.find.TAG("*",k),y=w+=null==v?1:Math.random()||.1,z=x.length;for(k&&(j=g===n||g||k);s!==z&&null!=(l=x[s]);s++){if(e&&l){o=0,g||l.ownerDocument===n||(m(l),h=!p);while(q=a[o++])if(q(l,g||n,h)){i.push(l);break}k&&(w=y)}c&&((l=!q&&l)&&r--,f&&t.push(l))}if(r+=s,c&&s!==r){o=0;while(q=b[o++])q(t,u,g,h);if(f){if(r>0)while(s--)t[s]||u[s]||(u[s]=F.call(i));u=ua(u)}H.apply(i,u),k&&!f&&u.length>0&&r+b.length>1&&fa.uniqueSort(i)}return k&&(w=y,j=v),t};return c?ha(f):f}return h=fa.compile=function(a,b){var c,d=[],e=[],f=A[a+" "];if(!f){b||(b=g(a)),c=b.length;while(c--)f=wa(b[c]),f[u]?d.push(f):e.push(f);f=A(a,xa(e,d)),f.selector=a}return f},i=fa.select=function(a,b,e,f){var i,j,k,l,m,n="function"==typeof a&&a,o=!f&&g(a=n.selector||a);if(e=e||[],1===o.length){if(j=o[0]=o[0].slice(0),j.length>2&&"ID"===(k=j[0]).type&&c.getById&&9===b.nodeType&&p&&d.relative[j[1].type]){if(b=(d.find.ID(k.matches[0].replace(ba,ca),b)||[])[0],!b)return e;n&&(b=b.parentNode),a=a.slice(j.shift().value.length)}i=W.needsContext.test(a)?0:j.length;while(i--){if(k=j[i],d.relative[l=k.type])break;if((m=d.find[l])&&(f=m(k.matches[0].replace(ba,ca),_.test(j[0].type)&&oa(b.parentNode)||b))){if(j.splice(i,1),a=f.length&&qa(j),!a)return H.apply(e,f),e;break}}}return(n||h(a,o))(f,b,!p,e,!b||_.test(a)&&oa(b.parentNode)||b),e},c.sortStable=u.split("").sort(B).join("")===u,c.detectDuplicates=!!l,m(),c.sortDetached=ia(function(a){return 1&a.compareDocumentPosition(n.createElement("div"))}),ia(function(a){return a.innerHTML="","#"===a.firstChild.getAttribute("href")})||ja("type|href|height|width",function(a,b,c){return c?void 0:a.getAttribute(b,"type"===b.toLowerCase()?1:2)}),c.attributes&&ia(function(a){return a.innerHTML="",a.firstChild.setAttribute("value",""),""===a.firstChild.getAttribute("value")})||ja("value",function(a,b,c){return c||"input"!==a.nodeName.toLowerCase()?void 0:a.defaultValue}),ia(function(a){return null==a.getAttribute("disabled")})||ja(K,function(a,b,c){var d;return c?void 0:a[b]===!0?b.toLowerCase():(d=a.getAttributeNode(b))&&d.specified?d.value:null}),fa}(a);n.find=t,n.expr=t.selectors,n.expr[":"]=n.expr.pseudos,n.uniqueSort=n.unique=t.uniqueSort,n.text=t.getText,n.isXMLDoc=t.isXML,n.contains=t.contains;var u=function(a,b,c){var d=[],e=void 0!==c;while((a=a[b])&&9!==a.nodeType)if(1===a.nodeType){if(e&&n(a).is(c))break;d.push(a)}return d},v=function(a,b){for(var c=[];a;a=a.nextSibling)1===a.nodeType&&a!==b&&c.push(a);return c},w=n.expr.match.needsContext,x=/^<([\w-]+)\s*\/?>(?:<\/\1>|)$/,y=/^.[^:#\[\.,]*$/;function z(a,b,c){if(n.isFunction(b))return n.grep(a,function(a,d){return!!b.call(a,d,a)!==c});if(b.nodeType)return n.grep(a,function(a){return a===b!==c});if("string"==typeof b){if(y.test(b))return n.filter(b,a,c);b=n.filter(b,a)}return n.grep(a,function(a){return n.inArray(a,b)>-1!==c})}n.filter=function(a,b,c){var d=b[0];return c&&(a=":not("+a+")"),1===b.length&&1===d.nodeType?n.find.matchesSelector(d,a)?[d]:[]:n.find.matches(a,n.grep(b,function(a){return 1===a.nodeType}))},n.fn.extend({find:function(a){var b,c=[],d=this,e=d.length;if("string"!=typeof a)return this.pushStack(n(a).filter(function(){for(b=0;e>b;b++)if(n.contains(d[b],this))return!0}));for(b=0;e>b;b++)n.find(a,d[b],c);return c=this.pushStack(e>1?n.unique(c):c),c.selector=this.selector?this.selector+" "+a:a,c},filter:function(a){return this.pushStack(z(this,a||[],!1))},not:function(a){return this.pushStack(z(this,a||[],!0))},is:function(a){return!!z(this,"string"==typeof a&&w.test(a)?n(a):a||[],!1).length}});var A,B=/^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]*))$/,C=n.fn.init=function(a,b,c){var e,f;if(!a)return this;if(c=c||A,"string"==typeof a){if(e="<"===a.charAt(0)&&">"===a.charAt(a.length-1)&&a.length>=3?[null,a,null]:B.exec(a),!e||!e[1]&&b)return!b||b.jquery?(b||c).find(a):this.constructor(b).find(a);if(e[1]){if(b=b instanceof n?b[0]:b,n.merge(this,n.parseHTML(e[1],b&&b.nodeType?b.ownerDocument||b:d,!0)),x.test(e[1])&&n.isPlainObject(b))for(e in b)n.isFunction(this[e])?this[e](b[e]):this.attr(e,b[e]);return this}if(f=d.getElementById(e[2]),f&&f.parentNode){if(f.id!==e[2])return A.find(a);this.length=1,this[0]=f}return this.context=d,this.selector=a,this}return a.nodeType?(this.context=this[0]=a,this.length=1,this):n.isFunction(a)?"undefined"!=typeof c.ready?c.ready(a):a(n):(void 0!==a.selector&&(this.selector=a.selector,this.context=a.context),n.makeArray(a,this))};C.prototype=n.fn,A=n(d);var D=/^(?:parents|prev(?:Until|All))/,E={children:!0,contents:!0,next:!0,prev:!0};n.fn.extend({has:function(a){var b,c=n(a,this),d=c.length;return this.filter(function(){for(b=0;d>b;b++)if(n.contains(this,c[b]))return!0})},closest:function(a,b){for(var c,d=0,e=this.length,f=[],g=w.test(a)||"string"!=typeof a?n(a,b||this.context):0;e>d;d++)for(c=this[d];c&&c!==b;c=c.parentNode)if(c.nodeType<11&&(g?g.index(c)>-1:1===c.nodeType&&n.find.matchesSelector(c,a))){f.push(c);break}return this.pushStack(f.length>1?n.uniqueSort(f):f)},index:function(a){return a?"string"==typeof a?n.inArray(this[0],n(a)):n.inArray(a.jquery?a[0]:a,this):this[0]&&this[0].parentNode?this.first().prevAll().length:-1},add:function(a,b){return this.pushStack(n.uniqueSort(n.merge(this.get(),n(a,b))))},addBack:function(a){return this.add(null==a?this.prevObject:this.prevObject.filter(a))}});function F(a,b){do a=a[b];while(a&&1!==a.nodeType);return a}n.each({parent:function(a){var b=a.parentNode;return b&&11!==b.nodeType?b:null},parents:function(a){return u(a,"parentNode")},parentsUntil:function(a,b,c){return u(a,"parentNode",c)},next:function(a){return F(a,"nextSibling")},prev:function(a){return F(a,"previousSibling")},nextAll:function(a){return u(a,"nextSibling")},prevAll:function(a){return u(a,"previousSibling")},nextUntil:function(a,b,c){return u(a,"nextSibling",c)},prevUntil:function(a,b,c){return u(a,"previousSibling",c)},siblings:function(a){return v((a.parentNode||{}).firstChild,a)},children:function(a){return v(a.firstChild)},contents:function(a){return n.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:n.merge([],a.childNodes)}},function(a,b){n.fn[a]=function(c,d){var e=n.map(this,b,c);return"Until"!==a.slice(-5)&&(d=c),d&&"string"==typeof d&&(e=n.filter(d,e)),this.length>1&&(E[a]||(e=n.uniqueSort(e)),D.test(a)&&(e=e.reverse())),this.pushStack(e)}});var G=/\S+/g;function H(a){var b={};return n.each(a.match(G)||[],function(a,c){b[c]=!0}),b}n.Callbacks=function(a){a="string"==typeof a?H(a):n.extend({},a);var b,c,d,e,f=[],g=[],h=-1,i=function(){for(e=a.once,d=b=!0;g.length;h=-1){c=g.shift();while(++h-1)f.splice(c,1),h>=c&&h--}),this},has:function(a){return a?n.inArray(a,f)>-1:f.length>0},empty:function(){return f&&(f=[]),this},disable:function(){return e=g=[],f=c="",this},disabled:function(){return!f},lock:function(){return e=!0,c||j.disable(),this},locked:function(){return!!e},fireWith:function(a,c){return e||(c=c||[],c=[a,c.slice?c.slice():c],g.push(c),b||i()),this},fire:function(){return j.fireWith(this,arguments),this},fired:function(){return!!d}};return j},n.extend({Deferred:function(a){var b=[["resolve","done",n.Callbacks("once memory"),"resolved"],["reject","fail",n.Callbacks("once memory"),"rejected"],["notify","progress",n.Callbacks("memory")]],c="pending",d={state:function(){return c},always:function(){return e.done(arguments).fail(arguments),this},then:function(){var a=arguments;return n.Deferred(function(c){n.each(b,function(b,f){var g=n.isFunction(a[b])&&a[b];e[f[1]](function(){var a=g&&g.apply(this,arguments);a&&n.isFunction(a.promise)?a.promise().progress(c.notify).done(c.resolve).fail(c.reject):c[f[0]+"With"](this===d?c.promise():this,g?[a]:arguments)})}),a=null}).promise()},promise:function(a){return null!=a?n.extend(a,d):d}},e={};return d.pipe=d.then,n.each(b,function(a,f){var g=f[2],h=f[3];d[f[1]]=g.add,h&&g.add(function(){c=h},b[1^a][2].disable,b[2][2].lock),e[f[0]]=function(){return e[f[0]+"With"](this===e?d:this,arguments),this},e[f[0]+"With"]=g.fireWith}),d.promise(e),a&&a.call(e,e),e},when:function(a){var b=0,c=e.call(arguments),d=c.length,f=1!==d||a&&n.isFunction(a.promise)?d:0,g=1===f?a:n.Deferred(),h=function(a,b,c){return function(d){b[a]=this,c[a]=arguments.length>1?e.call(arguments):d,c===i?g.notifyWith(b,c):--f||g.resolveWith(b,c)}},i,j,k;if(d>1)for(i=new Array(d),j=new Array(d),k=new Array(d);d>b;b++)c[b]&&n.isFunction(c[b].promise)?c[b].promise().progress(h(b,j,i)).done(h(b,k,c)).fail(g.reject):--f;return f||g.resolveWith(k,c),g.promise()}});var I;n.fn.ready=function(a){return n.ready.promise().done(a),this},n.extend({isReady:!1,readyWait:1,holdReady:function(a){a?n.readyWait++:n.ready(!0)},ready:function(a){(a===!0?--n.readyWait:n.isReady)||(n.isReady=!0,a!==!0&&--n.readyWait>0||(I.resolveWith(d,[n]),n.fn.triggerHandler&&(n(d).triggerHandler("ready"),n(d).off("ready"))))}});function J(){d.addEventListener?(d.removeEventListener("DOMContentLoaded",K),a.removeEventListener("load",K)):(d.detachEvent("onreadystatechange",K),a.detachEvent("onload",K))}function K(){(d.addEventListener||"load"===a.event.type||"complete"===d.readyState)&&(J(),n.ready())}n.ready.promise=function(b){if(!I)if(I=n.Deferred(),"complete"===d.readyState||"loading"!==d.readyState&&!d.documentElement.doScroll)a.setTimeout(n.ready);else if(d.addEventListener)d.addEventListener("DOMContentLoaded",K),a.addEventListener("load",K);else{d.attachEvent("onreadystatechange",K),a.attachEvent("onload",K);var c=!1;try{c=null==a.frameElement&&d.documentElement}catch(e){}c&&c.doScroll&&!function f(){if(!n.isReady){try{c.doScroll("left")}catch(b){return a.setTimeout(f,50)}J(),n.ready()}}()}return I.promise(b)},n.ready.promise();var L;for(L in n(l))break;l.ownFirst="0"===L,l.inlineBlockNeedsLayout=!1,n(function(){var a,b,c,e;c=d.getElementsByTagName("body")[0],c&&c.style&&(b=d.createElement("div"),e=d.createElement("div"),e.style.cssText="position:absolute;border:0;width:0;height:0;top:0;left:-9999px",c.appendChild(e).appendChild(b),"undefined"!=typeof b.style.zoom&&(b.style.cssText="display:inline;margin:0;border:0;padding:1px;width:1px;zoom:1",l.inlineBlockNeedsLayout=a=3===b.offsetWidth,a&&(c.style.zoom=1)),c.removeChild(e))}),function(){var a=d.createElement("div");l.deleteExpando=!0;try{delete a.test}catch(b){l.deleteExpando=!1}a=null}();var M=function(a){var b=n.noData[(a.nodeName+" ").toLowerCase()],c=+a.nodeType||1;return 1!==c&&9!==c?!1:!b||b!==!0&&a.getAttribute("classid")===b},N=/^(?:\{[\w\W]*\}|\[[\w\W]*\])$/,O=/([A-Z])/g;function P(a,b,c){if(void 0===c&&1===a.nodeType){var d="data-"+b.replace(O,"-$1").toLowerCase();if(c=a.getAttribute(d),"string"==typeof c){try{c="true"===c?!0:"false"===c?!1:"null"===c?null:+c+""===c?+c:N.test(c)?n.parseJSON(c):c}catch(e){}n.data(a,b,c)}else c=void 0; -}return c}function Q(a){var b;for(b in a)if(("data"!==b||!n.isEmptyObject(a[b]))&&"toJSON"!==b)return!1;return!0}function R(a,b,d,e){if(M(a)){var f,g,h=n.expando,i=a.nodeType,j=i?n.cache:a,k=i?a[h]:a[h]&&h;if(k&&j[k]&&(e||j[k].data)||void 0!==d||"string"!=typeof b)return k||(k=i?a[h]=c.pop()||n.guid++:h),j[k]||(j[k]=i?{}:{toJSON:n.noop}),"object"!=typeof b&&"function"!=typeof b||(e?j[k]=n.extend(j[k],b):j[k].data=n.extend(j[k].data,b)),g=j[k],e||(g.data||(g.data={}),g=g.data),void 0!==d&&(g[n.camelCase(b)]=d),"string"==typeof b?(f=g[b],null==f&&(f=g[n.camelCase(b)])):f=g,f}}function S(a,b,c){if(M(a)){var d,e,f=a.nodeType,g=f?n.cache:a,h=f?a[n.expando]:n.expando;if(g[h]){if(b&&(d=c?g[h]:g[h].data)){n.isArray(b)?b=b.concat(n.map(b,n.camelCase)):b in d?b=[b]:(b=n.camelCase(b),b=b in d?[b]:b.split(" ")),e=b.length;while(e--)delete d[b[e]];if(c?!Q(d):!n.isEmptyObject(d))return}(c||(delete g[h].data,Q(g[h])))&&(f?n.cleanData([a],!0):l.deleteExpando||g!=g.window?delete g[h]:g[h]=void 0)}}}n.extend({cache:{},noData:{"applet ":!0,"embed ":!0,"object ":"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"},hasData:function(a){return a=a.nodeType?n.cache[a[n.expando]]:a[n.expando],!!a&&!Q(a)},data:function(a,b,c){return R(a,b,c)},removeData:function(a,b){return S(a,b)},_data:function(a,b,c){return R(a,b,c,!0)},_removeData:function(a,b){return S(a,b,!0)}}),n.fn.extend({data:function(a,b){var c,d,e,f=this[0],g=f&&f.attributes;if(void 0===a){if(this.length&&(e=n.data(f),1===f.nodeType&&!n._data(f,"parsedAttrs"))){c=g.length;while(c--)g[c]&&(d=g[c].name,0===d.indexOf("data-")&&(d=n.camelCase(d.slice(5)),P(f,d,e[d])));n._data(f,"parsedAttrs",!0)}return e}return"object"==typeof a?this.each(function(){n.data(this,a)}):arguments.length>1?this.each(function(){n.data(this,a,b)}):f?P(f,a,n.data(f,a)):void 0},removeData:function(a){return this.each(function(){n.removeData(this,a)})}}),n.extend({queue:function(a,b,c){var d;return a?(b=(b||"fx")+"queue",d=n._data(a,b),c&&(!d||n.isArray(c)?d=n._data(a,b,n.makeArray(c)):d.push(c)),d||[]):void 0},dequeue:function(a,b){b=b||"fx";var c=n.queue(a,b),d=c.length,e=c.shift(),f=n._queueHooks(a,b),g=function(){n.dequeue(a,b)};"inprogress"===e&&(e=c.shift(),d--),e&&("fx"===b&&c.unshift("inprogress"),delete f.stop,e.call(a,g,f)),!d&&f&&f.empty.fire()},_queueHooks:function(a,b){var c=b+"queueHooks";return n._data(a,c)||n._data(a,c,{empty:n.Callbacks("once memory").add(function(){n._removeData(a,b+"queue"),n._removeData(a,c)})})}}),n.fn.extend({queue:function(a,b){var c=2;return"string"!=typeof a&&(b=a,a="fx",c--),arguments.lengthh;h++)b(a[h],c,g?d:d.call(a[h],h,b(a[h],c)));return e?a:j?b.call(a):i?b(a[0],c):f},Z=/^(?:checkbox|radio)$/i,$=/<([\w:-]+)/,_=/^$|\/(?:java|ecma)script/i,aa=/^\s+/,ba="abbr|article|aside|audio|bdi|canvas|data|datalist|details|dialog|figcaption|figure|footer|header|hgroup|main|mark|meter|nav|output|picture|progress|section|summary|template|time|video";function ca(a){var b=ba.split("|"),c=a.createDocumentFragment();if(c.createElement)while(b.length)c.createElement(b.pop());return c}!function(){var a=d.createElement("div"),b=d.createDocumentFragment(),c=d.createElement("input");a.innerHTML="
a",l.leadingWhitespace=3===a.firstChild.nodeType,l.tbody=!a.getElementsByTagName("tbody").length,l.htmlSerialize=!!a.getElementsByTagName("link").length,l.html5Clone="<:nav>"!==d.createElement("nav").cloneNode(!0).outerHTML,c.type="checkbox",c.checked=!0,b.appendChild(c),l.appendChecked=c.checked,a.innerHTML="",l.noCloneChecked=!!a.cloneNode(!0).lastChild.defaultValue,b.appendChild(a),c=d.createElement("input"),c.setAttribute("type","radio"),c.setAttribute("checked","checked"),c.setAttribute("name","t"),a.appendChild(c),l.checkClone=a.cloneNode(!0).cloneNode(!0).lastChild.checked,l.noCloneEvent=!!a.addEventListener,a[n.expando]=1,l.attributes=!a.getAttribute(n.expando)}();var da={option:[1,""],legend:[1,"
","
"],area:[1,"",""],param:[1,"",""],thead:[1,"","
"],tr:[2,"","
"],col:[2,"","
"],td:[3,"","
"],_default:l.htmlSerialize?[0,"",""]:[1,"X
","
"]};da.optgroup=da.option,da.tbody=da.tfoot=da.colgroup=da.caption=da.thead,da.th=da.td;function ea(a,b){var c,d,e=0,f="undefined"!=typeof a.getElementsByTagName?a.getElementsByTagName(b||"*"):"undefined"!=typeof a.querySelectorAll?a.querySelectorAll(b||"*"):void 0;if(!f)for(f=[],c=a.childNodes||a;null!=(d=c[e]);e++)!b||n.nodeName(d,b)?f.push(d):n.merge(f,ea(d,b));return void 0===b||b&&n.nodeName(a,b)?n.merge([a],f):f}function fa(a,b){for(var c,d=0;null!=(c=a[d]);d++)n._data(c,"globalEval",!b||n._data(b[d],"globalEval"))}var ga=/<|&#?\w+;/,ha=/r;r++)if(g=a[r],g||0===g)if("object"===n.type(g))n.merge(q,g.nodeType?[g]:g);else if(ga.test(g)){i=i||p.appendChild(b.createElement("div")),j=($.exec(g)||["",""])[1].toLowerCase(),m=da[j]||da._default,i.innerHTML=m[1]+n.htmlPrefilter(g)+m[2],f=m[0];while(f--)i=i.lastChild;if(!l.leadingWhitespace&&aa.test(g)&&q.push(b.createTextNode(aa.exec(g)[0])),!l.tbody){g="table"!==j||ha.test(g)?""!==m[1]||ha.test(g)?0:i:i.firstChild,f=g&&g.childNodes.length;while(f--)n.nodeName(k=g.childNodes[f],"tbody")&&!k.childNodes.length&&g.removeChild(k)}n.merge(q,i.childNodes),i.textContent="";while(i.firstChild)i.removeChild(i.firstChild);i=p.lastChild}else q.push(b.createTextNode(g));i&&p.removeChild(i),l.appendChecked||n.grep(ea(q,"input"),ia),r=0;while(g=q[r++])if(d&&n.inArray(g,d)>-1)e&&e.push(g);else if(h=n.contains(g.ownerDocument,g),i=ea(p.appendChild(g),"script"),h&&fa(i),c){f=0;while(g=i[f++])_.test(g.type||"")&&c.push(g)}return i=null,p}!function(){var b,c,e=d.createElement("div");for(b in{submit:!0,change:!0,focusin:!0})c="on"+b,(l[b]=c in a)||(e.setAttribute(c,"t"),l[b]=e.attributes[c].expando===!1);e=null}();var ka=/^(?:input|select|textarea)$/i,la=/^key/,ma=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,na=/^(?:focusinfocus|focusoutblur)$/,oa=/^([^.]*)(?:\.(.+)|)/;function pa(){return!0}function qa(){return!1}function ra(){try{return d.activeElement}catch(a){}}function sa(a,b,c,d,e,f){var g,h;if("object"==typeof b){"string"!=typeof c&&(d=d||c,c=void 0);for(h in b)sa(a,h,c,d,b[h],f);return a}if(null==d&&null==e?(e=c,d=c=void 0):null==e&&("string"==typeof c?(e=d,d=void 0):(e=d,d=c,c=void 0)),e===!1)e=qa;else if(!e)return a;return 1===f&&(g=e,e=function(a){return n().off(a),g.apply(this,arguments)},e.guid=g.guid||(g.guid=n.guid++)),a.each(function(){n.event.add(this,b,e,d,c)})}n.event={global:{},add:function(a,b,c,d,e){var f,g,h,i,j,k,l,m,o,p,q,r=n._data(a);if(r){c.handler&&(i=c,c=i.handler,e=i.selector),c.guid||(c.guid=n.guid++),(g=r.events)||(g=r.events={}),(k=r.handle)||(k=r.handle=function(a){return"undefined"==typeof n||a&&n.event.triggered===a.type?void 0:n.event.dispatch.apply(k.elem,arguments)},k.elem=a),b=(b||"").match(G)||[""],h=b.length;while(h--)f=oa.exec(b[h])||[],o=q=f[1],p=(f[2]||"").split(".").sort(),o&&(j=n.event.special[o]||{},o=(e?j.delegateType:j.bindType)||o,j=n.event.special[o]||{},l=n.extend({type:o,origType:q,data:d,handler:c,guid:c.guid,selector:e,needsContext:e&&n.expr.match.needsContext.test(e),namespace:p.join(".")},i),(m=g[o])||(m=g[o]=[],m.delegateCount=0,j.setup&&j.setup.call(a,d,p,k)!==!1||(a.addEventListener?a.addEventListener(o,k,!1):a.attachEvent&&a.attachEvent("on"+o,k))),j.add&&(j.add.call(a,l),l.handler.guid||(l.handler.guid=c.guid)),e?m.splice(m.delegateCount++,0,l):m.push(l),n.event.global[o]=!0);a=null}},remove:function(a,b,c,d,e){var f,g,h,i,j,k,l,m,o,p,q,r=n.hasData(a)&&n._data(a);if(r&&(k=r.events)){b=(b||"").match(G)||[""],j=b.length;while(j--)if(h=oa.exec(b[j])||[],o=q=h[1],p=(h[2]||"").split(".").sort(),o){l=n.event.special[o]||{},o=(d?l.delegateType:l.bindType)||o,m=k[o]||[],h=h[2]&&new RegExp("(^|\\.)"+p.join("\\.(?:.*\\.|)")+"(\\.|$)"),i=f=m.length;while(f--)g=m[f],!e&&q!==g.origType||c&&c.guid!==g.guid||h&&!h.test(g.namespace)||d&&d!==g.selector&&("**"!==d||!g.selector)||(m.splice(f,1),g.selector&&m.delegateCount--,l.remove&&l.remove.call(a,g));i&&!m.length&&(l.teardown&&l.teardown.call(a,p,r.handle)!==!1||n.removeEvent(a,o,r.handle),delete k[o])}else for(o in k)n.event.remove(a,o+b[j],c,d,!0);n.isEmptyObject(k)&&(delete r.handle,n._removeData(a,"events"))}},trigger:function(b,c,e,f){var g,h,i,j,l,m,o,p=[e||d],q=k.call(b,"type")?b.type:b,r=k.call(b,"namespace")?b.namespace.split("."):[];if(i=m=e=e||d,3!==e.nodeType&&8!==e.nodeType&&!na.test(q+n.event.triggered)&&(q.indexOf(".")>-1&&(r=q.split("."),q=r.shift(),r.sort()),h=q.indexOf(":")<0&&"on"+q,b=b[n.expando]?b:new n.Event(q,"object"==typeof b&&b),b.isTrigger=f?2:3,b.namespace=r.join("."),b.rnamespace=b.namespace?new RegExp("(^|\\.)"+r.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,b.result=void 0,b.target||(b.target=e),c=null==c?[b]:n.makeArray(c,[b]),l=n.event.special[q]||{},f||!l.trigger||l.trigger.apply(e,c)!==!1)){if(!f&&!l.noBubble&&!n.isWindow(e)){for(j=l.delegateType||q,na.test(j+q)||(i=i.parentNode);i;i=i.parentNode)p.push(i),m=i;m===(e.ownerDocument||d)&&p.push(m.defaultView||m.parentWindow||a)}o=0;while((i=p[o++])&&!b.isPropagationStopped())b.type=o>1?j:l.bindType||q,g=(n._data(i,"events")||{})[b.type]&&n._data(i,"handle"),g&&g.apply(i,c),g=h&&i[h],g&&g.apply&&M(i)&&(b.result=g.apply(i,c),b.result===!1&&b.preventDefault());if(b.type=q,!f&&!b.isDefaultPrevented()&&(!l._default||l._default.apply(p.pop(),c)===!1)&&M(e)&&h&&e[q]&&!n.isWindow(e)){m=e[h],m&&(e[h]=null),n.event.triggered=q;try{e[q]()}catch(s){}n.event.triggered=void 0,m&&(e[h]=m)}return b.result}},dispatch:function(a){a=n.event.fix(a);var b,c,d,f,g,h=[],i=e.call(arguments),j=(n._data(this,"events")||{})[a.type]||[],k=n.event.special[a.type]||{};if(i[0]=a,a.delegateTarget=this,!k.preDispatch||k.preDispatch.call(this,a)!==!1){h=n.event.handlers.call(this,a,j),b=0;while((f=h[b++])&&!a.isPropagationStopped()){a.currentTarget=f.elem,c=0;while((g=f.handlers[c++])&&!a.isImmediatePropagationStopped())a.rnamespace&&!a.rnamespace.test(g.namespace)||(a.handleObj=g,a.data=g.data,d=((n.event.special[g.origType]||{}).handle||g.handler).apply(f.elem,i),void 0!==d&&(a.result=d)===!1&&(a.preventDefault(),a.stopPropagation()))}return k.postDispatch&&k.postDispatch.call(this,a),a.result}},handlers:function(a,b){var c,d,e,f,g=[],h=b.delegateCount,i=a.target;if(h&&i.nodeType&&("click"!==a.type||isNaN(a.button)||a.button<1))for(;i!=this;i=i.parentNode||this)if(1===i.nodeType&&(i.disabled!==!0||"click"!==a.type)){for(d=[],c=0;h>c;c++)f=b[c],e=f.selector+" ",void 0===d[e]&&(d[e]=f.needsContext?n(e,this).index(i)>-1:n.find(e,this,null,[i]).length),d[e]&&d.push(f);d.length&&g.push({elem:i,handlers:d})}return h]","i"),va=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:-]+)[^>]*)\/>/gi,wa=/\s*$/g,Aa=ca(d),Ba=Aa.appendChild(d.createElement("div"));function Ca(a,b){return n.nodeName(a,"table")&&n.nodeName(11!==b.nodeType?b:b.firstChild,"tr")?a.getElementsByTagName("tbody")[0]||a.appendChild(a.ownerDocument.createElement("tbody")):a}function Da(a){return a.type=(null!==n.find.attr(a,"type"))+"/"+a.type,a}function Ea(a){var b=ya.exec(a.type);return b?a.type=b[1]:a.removeAttribute("type"),a}function Fa(a,b){if(1===b.nodeType&&n.hasData(a)){var c,d,e,f=n._data(a),g=n._data(b,f),h=f.events;if(h){delete g.handle,g.events={};for(c in h)for(d=0,e=h[c].length;e>d;d++)n.event.add(b,c,h[c][d])}g.data&&(g.data=n.extend({},g.data))}}function Ga(a,b){var c,d,e;if(1===b.nodeType){if(c=b.nodeName.toLowerCase(),!l.noCloneEvent&&b[n.expando]){e=n._data(b);for(d in e.events)n.removeEvent(b,d,e.handle);b.removeAttribute(n.expando)}"script"===c&&b.text!==a.text?(Da(b).text=a.text,Ea(b)):"object"===c?(b.parentNode&&(b.outerHTML=a.outerHTML),l.html5Clone&&a.innerHTML&&!n.trim(b.innerHTML)&&(b.innerHTML=a.innerHTML)):"input"===c&&Z.test(a.type)?(b.defaultChecked=b.checked=a.checked,b.value!==a.value&&(b.value=a.value)):"option"===c?b.defaultSelected=b.selected=a.defaultSelected:"input"!==c&&"textarea"!==c||(b.defaultValue=a.defaultValue)}}function Ha(a,b,c,d){b=f.apply([],b);var e,g,h,i,j,k,m=0,o=a.length,p=o-1,q=b[0],r=n.isFunction(q);if(r||o>1&&"string"==typeof q&&!l.checkClone&&xa.test(q))return a.each(function(e){var f=a.eq(e);r&&(b[0]=q.call(this,e,f.html())),Ha(f,b,c,d)});if(o&&(k=ja(b,a[0].ownerDocument,!1,a,d),e=k.firstChild,1===k.childNodes.length&&(k=e),e||d)){for(i=n.map(ea(k,"script"),Da),h=i.length;o>m;m++)g=k,m!==p&&(g=n.clone(g,!0,!0),h&&n.merge(i,ea(g,"script"))),c.call(a[m],g,m);if(h)for(j=i[i.length-1].ownerDocument,n.map(i,Ea),m=0;h>m;m++)g=i[m],_.test(g.type||"")&&!n._data(g,"globalEval")&&n.contains(j,g)&&(g.src?n._evalUrl&&n._evalUrl(g.src):n.globalEval((g.text||g.textContent||g.innerHTML||"").replace(za,"")));k=e=null}return a}function Ia(a,b,c){for(var d,e=b?n.filter(b,a):a,f=0;null!=(d=e[f]);f++)c||1!==d.nodeType||n.cleanData(ea(d)),d.parentNode&&(c&&n.contains(d.ownerDocument,d)&&fa(ea(d,"script")),d.parentNode.removeChild(d));return a}n.extend({htmlPrefilter:function(a){return a.replace(va,"<$1>")},clone:function(a,b,c){var d,e,f,g,h,i=n.contains(a.ownerDocument,a);if(l.html5Clone||n.isXMLDoc(a)||!ua.test("<"+a.nodeName+">")?f=a.cloneNode(!0):(Ba.innerHTML=a.outerHTML,Ba.removeChild(f=Ba.firstChild)),!(l.noCloneEvent&&l.noCloneChecked||1!==a.nodeType&&11!==a.nodeType||n.isXMLDoc(a)))for(d=ea(f),h=ea(a),g=0;null!=(e=h[g]);++g)d[g]&&Ga(e,d[g]);if(b)if(c)for(h=h||ea(a),d=d||ea(f),g=0;null!=(e=h[g]);g++)Fa(e,d[g]);else Fa(a,f);return d=ea(f,"script"),d.length>0&&fa(d,!i&&ea(a,"script")),d=h=e=null,f},cleanData:function(a,b){for(var d,e,f,g,h=0,i=n.expando,j=n.cache,k=l.attributes,m=n.event.special;null!=(d=a[h]);h++)if((b||M(d))&&(f=d[i],g=f&&j[f])){if(g.events)for(e in g.events)m[e]?n.event.remove(d,e):n.removeEvent(d,e,g.handle);j[f]&&(delete j[f],k||"undefined"==typeof d.removeAttribute?d[i]=void 0:d.removeAttribute(i),c.push(f))}}}),n.fn.extend({domManip:Ha,detach:function(a){return Ia(this,a,!0)},remove:function(a){return Ia(this,a)},text:function(a){return Y(this,function(a){return void 0===a?n.text(this):this.empty().append((this[0]&&this[0].ownerDocument||d).createTextNode(a))},null,a,arguments.length)},append:function(){return Ha(this,arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=Ca(this,a);b.appendChild(a)}})},prepend:function(){return Ha(this,arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=Ca(this,a);b.insertBefore(a,b.firstChild)}})},before:function(){return Ha(this,arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this)})},after:function(){return Ha(this,arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this.nextSibling)})},empty:function(){for(var a,b=0;null!=(a=this[b]);b++){1===a.nodeType&&n.cleanData(ea(a,!1));while(a.firstChild)a.removeChild(a.firstChild);a.options&&n.nodeName(a,"select")&&(a.options.length=0)}return this},clone:function(a,b){return a=null==a?!1:a,b=null==b?a:b,this.map(function(){return n.clone(this,a,b)})},html:function(a){return Y(this,function(a){var b=this[0]||{},c=0,d=this.length;if(void 0===a)return 1===b.nodeType?b.innerHTML.replace(ta,""):void 0;if("string"==typeof a&&!wa.test(a)&&(l.htmlSerialize||!ua.test(a))&&(l.leadingWhitespace||!aa.test(a))&&!da[($.exec(a)||["",""])[1].toLowerCase()]){a=n.htmlPrefilter(a);try{for(;d>c;c++)b=this[c]||{},1===b.nodeType&&(n.cleanData(ea(b,!1)),b.innerHTML=a);b=0}catch(e){}}b&&this.empty().append(a)},null,a,arguments.length)},replaceWith:function(){var a=[];return Ha(this,arguments,function(b){var c=this.parentNode;n.inArray(this,a)<0&&(n.cleanData(ea(this)),c&&c.replaceChild(b,this))},a)}}),n.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){n.fn[a]=function(a){for(var c,d=0,e=[],f=n(a),h=f.length-1;h>=d;d++)c=d===h?this:this.clone(!0),n(f[d])[b](c),g.apply(e,c.get());return this.pushStack(e)}});var Ja,Ka={HTML:"block",BODY:"block"};function La(a,b){var c=n(b.createElement(a)).appendTo(b.body),d=n.css(c[0],"display");return c.detach(),d}function Ma(a){var b=d,c=Ka[a];return c||(c=La(a,b),"none"!==c&&c||(Ja=(Ja||n("