diff --git a/docs/ref/index.txt b/docs/ref/index.txt index 8fc99ada81..bd0aa519af 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -21,6 +21,7 @@ API Reference migration-operations models/index paginator + parsers request-response schema-editor settings diff --git a/docs/ref/parsers.txt b/docs/ref/parsers.txt new file mode 100644 index 0000000000..5735bf4b1a --- /dev/null +++ b/docs/ref/parsers.txt @@ -0,0 +1,58 @@ +============ +HTTP Parsers +============ + +.. module:: django.http.parsers + :synopsis: Classes dealing with parsing HTTP requests. + +# TODO See about stitching this back into ``request-response.txt`` + +Parsers +======= + +.. class:: BaseParser + + .. attribute:: media_type + + The media types this class can accept. Example ``application/json``. + + .. method:: can_handle(media_type) + + This method accepts a media type and returns true if the parser can parse + this type. By default, this method compares the string provided to + :attr:`.media_type` and returns ``True`` if it's an exact match. + + You may wish to customize this method if your custom parser can accept + multiple types. + + .. method:: BaseParser.parse(request) + + This method parses the requests body and returns a two-tuple being the + parsed ``data`` and ``FILES``. For parsers which do not return ``FILES`` an + empty ``MultiValueDict`` is returned. + +All parsers should inherit from the ``BaseParser`` class. This class has the +following attributes and methods + +Provided parsers +================ + +Django provides the following parsers. + +.. class:: FormParser + + .. attribute:: media_type + + ``"application/x-www-form-urlencoded"`` + +Parses HTML form content (). The ``parse()`` method returns a +``QueryDict`` for ``data`` and an empty ``MultiValueDict`` for ``FILES``. + +.. class:: MultiPartParser + + .. attribute:: media_type + + ``"multipart/form-data"`` + +Parses multipart form content and supports file uploads. The method returns +a ``QueryDict`` for ``data`` and an ``MultiValueDict`` for ``FILES``.