encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2025-02-03 13:14:30 +03:00
Code Issues Packages Projects Releases Wiki Activity

check in marko's docs

Browse Source
This commit is contained in:
Tom Christie 2011-05-23 17:09:29 +01:00
commit 698df527a3
6 changed files with 58 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
djangorestframework/compat.py
View File

@ -1,5 +1,5 @@
"""
Compatability module to provide support for backwards compatability with older versions of django/python
The :mod:`compatability` module provides support for backwards compatability with older versions of django/python.
"""
# cStringIO only if it's available
@ -42,7 +42,7 @@ except ImportError:
__ http://www.djangoproject.com/documentation/testing/#the-test-client
Once you have a :obj:`request` object you can pass it to any :func:`view` function,
Once you have a `request` object you can pass it to any :func:`view` function,
just as if that :func:`view` had been hooked up using a URLconf.
"""
def request(self, **request):

8
djangorestframework/permissions.py
View File

@ -1,3 +1,9 @@
"""
The :mod:`permissions` module bundles a set of permission classes that are used
for checking if a request passes a certain set of constraints. You can assign a permision
class to your view by setting your View's :attr:`permissions` class attribute.
"""
from django.core.cache import cache
from djangorestframework import status
from djangorestframework.response import ErrorResponse
@ -36,7 +42,7 @@ class BasePermission(object):
def check_permission(self, auth):
"""
Should simply return, or raise an :class:`response.ErrorResponse`.
Should simply return, or raise an :exc:`response.ErrorResponse`.
"""
pass

54
djangorestframework/resources.py
View File

@ -124,8 +124,8 @@ class BaseResource(object):
def validate_request(self, data, files):
"""
Given the request data return the cleaned, validated content.
Typically raises a ErrorResponse with status code 400 (Bad Request) on failure.
Given the request content return the cleaned, validated content.
Typically raises a :exc:`response.ErrorResponse` with status code 400 (Bad Request) on failure.
"""
return data
@ -160,28 +160,28 @@ class Resource(BaseResource):
class FormResource(Resource):
"""
Resource class that uses forms for validation.
Also provides a get_bound_form() method which may be used by some renderers.
Also provides a :meth:`get_bound_form` method which may be used by some renderers.
On calling validate() this validator may set a `.bound_form_instance` attribute on the
On calling :meth:`validate_request` this validator may set a :attr:`bound_form_instance` attribute on the
view, which may be used by some renderers.
"""
"""
The form class that should be used for request validation.
"""
form = None
"""
The :class:`Form` class that should be used for request validation.
"""
def validate_request(self, data, files):
"""
Given some content as input return some cleaned, validated content.
Raises a ErrorResponse with status code 400 (Bad Request) on failure.
Raises a :exc:`response.ErrorResponse` with status code 400 (Bad Request) on failure.
Validation is standard form validation, with an additional constraint that no extra unknown fields may be supplied.
Validation is standard form validation, with an additional constraint that *no extra unknown fields* may be supplied.
On failure the ErrorResponse content is a dict which may contain 'errors' and 'field-errors' keys.
If the 'errors' key exists it is a list of strings of non-field errors.
If the 'field-errors' key exists it is a dict of {field name as string: list of errors as strings}.
On failure the :exc:`response.ErrorResponse` content is a dict which may contain :obj:`'errors'` and :obj:`'field-errors'` keys.
If the :obj:`'errors'` key exists it is a list of strings of non-field errors.
If the :obj:`'field-errors'` key exists it is a dict of ``{'field name as string': ['errors as strings', ...]}``.
"""
return self._validate(data, files)
@ -277,7 +277,7 @@ class FormResource(Resource):
def get_bound_form(self, data=None, files=None):
"""
Given some content return a Django form bound to that content.
If form validation is turned off (form class attribute is None) then returns None.
If form validation is turned off (:attr:`form` class attribute is :const:`None`) then returns :const:`None`.
"""
if not self.form:
return None
@ -305,7 +305,7 @@ class FormResource(Resource):
class ModelResource(FormResource):
"""
Resource class that uses forms for validation and otherwise falls back to a model form if no form is set.
Also provides a get_bound_form() method which may be used by some renderers.
Also provides a :meth:`get_bound_form` method which may be used by some renderers.
"""
# Auto-register new ModelResource classes into _model_to_resource
@ -313,7 +313,7 @@ class ModelResource(FormResource):
"""
The form class that should be used for request validation.
If set to ``None`` then the default model form validation will be used.
If set to :const:`None` then the default model form validation will be used.
"""
form = None
@ -330,18 +330,18 @@ class ModelResource(FormResource):
The name of a model field.
The name of an attribute on the model.
The name of an attribute on the resource.
The name of an method on the model, with a signature like ``func(self)``.
The name of an method on the resource, with a signature like ``func(self, instance)``.
The name of a method on the model, with a signature like ``func(self)``.
The name of a method on the resource, with a signature like ``func(self, instance)``.
"""
fields = None
"""
The list of fields to exclude. This is only used if ``fields`` is not set.
The list of fields to exclude. This is only used if :attr:`fields` is not set.
"""
exclude = ('id', 'pk')
"""
The list of extra fields to include. This is only used if ``fields`` is not set.
The list of extra fields to include. This is only used if :attr:`fields` is not set.
"""
include = ('url',)
@ -349,16 +349,16 @@ class ModelResource(FormResource):
def validate_request(self, data, files):
"""
Given some content as input return some cleaned, validated content.
Raises a ErrorResponse with status code 400 (Bad Request) on failure.
Raises a :exc:`response.ErrorResponse` with status code 400 (Bad Request) on failure.
Validation is standard form or model form validation,
with an additional constraint that no extra unknown fields may be supplied,
and that all fields specified by the fields class attribute must be supplied,
even if they are not validated by the form/model form.
On failure the ErrorResponse content is a dict which may contain 'errors' and 'field-errors' keys.
If the 'errors' key exists it is a list of strings of non-field errors.
If the 'field-errors' key exists it is a dict of {field name as string: list of errors as strings}.
On failure the ErrorResponse content is a dict which may contain :obj:`'errors'` and :obj:`'field-errors'` keys.
If the :obj:`'errors'` key exists it is a list of strings of non-field errors.
If the ''field-errors'` key exists it is a dict of {field name as string: list of errors as strings}.
"""
return self._validate(data, files, allowed_extra_fields=self._property_fields_set)
@ -367,7 +367,7 @@ class ModelResource(FormResource):
"""
Given some content return a ``Form`` instance bound to that content.
If the form class attribute has been explicitly set then that class will be used
If the :attr:`form` class attribute has been explicitly set then that class will be used
to create the Form, otherwise the model will be used to create a ModelForm.
"""
@ -396,9 +396,9 @@ class ModelResource(FormResource):
def url(self, instance):
"""
Attempts to reverse resolve the url of the given model instance for this resource.
Attempts to reverse resolve the url of the given model *instance* for this resource.
Requires a ``View`` with ``InstanceMixin`` to have been created for this resource.
Requires a ``View`` with :class:`mixins.InstanceMixin` to have been created for this resource.
This method can be overridden if you need to set the resource url reversing explicitly.
"""

7
djangorestframework/response.py
View File

@ -1,3 +1,10 @@
"""
The :mod:`response` module provides Response classes you can use in your
views to return a certain HTTP response. Typically a response is *rendered*
into a HTTP response depending on what renderers are set on your view and
als depending on the accept header of the request.
"""
from django.core.handlers.wsgi import STATUS_CODE_TEXT
__all__ = ('Response', 'ErrorResponse')

19
djangorestframework/views.py
View File

@ -1,3 +1,10 @@
"""
The :mod:`views` module provides the Views you will most probably
be subclassing in your implementation.
By setting or modifying class attributes on your view, you change it's predefined behaviour.
"""
from django.core.urlresolvers import set_script_prefix
from django.views.decorators.csrf import csrf_exempt
@ -26,25 +33,25 @@ class BaseView(ResourceMixin, RequestMixin, ResponseMixin, AuthMixin, View):
# Use the base resource by default
resource = resources.Resource
# List of renderers the resource can serialize the response with, ordered by preference.
renderers = ( renderers.JSONRenderer,
renderers.DocumentingHTMLRenderer,
renderers.DocumentingXHTMLRenderer,
renderers.DocumentingPlainTextRenderer,
renderers.XMLRenderer )
# List of parsers the resource can parse the request with.
""" List of renderers the resource can serialize the response with, ordered by preference."""
parsers = ( parsers.JSONParser,
parsers.FormParser,
parsers.MultiPartParser )
""" List of parsers the resource can parse the request with."""
# List of all authenticating methods to attempt.
authentication = ( authentication.UserLoggedInAuthenticaton,
authentication.BasicAuthenticaton )
""" List of all authenticating methods to attempt."""
# List of all permissions that must be checked.
permissions = ( permissions.FullAnonAccess, )
""" List of all permissions that must be checked."""
# Allow name and description for the Resource to be set explicitly,
# overiding the default classname/docstring behaviour.
# These are used for documentation in the standard html and text renderers.

135
docs/library/resource.rst
View File

@ -1,136 +1,5 @@
:mod:`resource`
===============
.. module:: resource
The :mod:`resource` module is the core of Django REST framework. It provides the :class:`Resource` base class which handles incoming HTTP requests and maps them to method calls, performing authentication, input deserialization, input validation and output serialization.
Resources are created by sublassing :class:`Resource`, setting a number of class attributes, and overriding one or more methods.
.. class:: Resource
:class:`Resource` class attributes
----------------------------------
The following class attributes determine the behavior of the Resource and are intended to be overridden.
.. attribute:: Resource.allowed_methods
A list of the HTTP methods that the Resource supports.
HTTP requests to the resource that do not map to an allowed operation will result in a 405 Method Not Allowed response.
Default: ``('GET',)``
.. attribute:: Resource.anon_allowed_methods
A list of the HTTP methods that the Resource supports for unauthenticated users.
Unauthenticated HTTP requests to the resource that do not map to an allowed operation will result in a 405 Method Not Allowed response.
Default: ``()``
.. attribute:: Resource.emitters
The list of emitters that the Resource supports. This determines which media types the resource can serialize it's output to. Clients can specify which media types they accept using standard HTTP content negotiation via the Accept header. (See `RFC 2616 - Sec 14.1 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html>`_) Clients can also override this standard content negotiation by specifying a `_format` ...
The :mod:`emitters` module provides the :class:`BaseEmitter` class and a set of default emitters, including emitters for JSON and XML, as well as emitters for HTML and Plain Text which provide for a self documenting API.
The ordering of the Emitters is important as it determines an order of preference.
Default: ``(emitters.JSONEmitter, emitters.DocumentingHTMLEmitter, emitters.DocumentingXHTMLEmitter, emitters.DocumentingPlainTextEmitter, emitters.XMLEmitter)``
.. attribute:: Resource.parsers
The list of parsers that the Resource supports. This determines which media types the resource can accept as input for incoming HTTP requests. (Typically PUT and POST requests).
The ordering of the Parsers may be considered informative of preference but is not used ...
Default: ``(parsers.JSONParser, parsers.XMLParser, parsers.FormParser)``
.. attribute:: Resource.authenticators
The list of authenticators that the Resource supports. This determines which authentication methods (eg Basic, Digest, OAuth) are used to authenticate requests.
Default: ``(authenticators.UserLoggedInAuthenticator, authenticators.BasicAuthenticator)``
.. attribute:: Resource.form
If not None, this attribute should be a Django form which will be used to validate any request data.
This attribute is typically only used for POST or PUT requests to the resource.
Deafult: ``None``
.. attribute:: Resource.callmap
Maps HTTP methods to function calls on the :class:`Resource`. It may be overridden in order to add support for other HTTP methods such as HEAD, OPTIONS and PATCH, or in order to map methods to different function names, for example to use a more `CRUD <http://en.wikipedia.org/wiki/Create,_read,_update_and_delete>`_ like style.
Default: ``{ 'GET': 'get', 'POST': 'post', 'PUT': 'put', 'DELETE': 'delete' }``
:class:`Resource` methods
-------------------------
.. method:: Resource.get
.. method:: Resource.post
.. method:: Resource.put
.. method:: Resource.delete
.. method:: Resource.authenticate
.. method:: Resource.reverse
:class:`Resource` properties
----------------------------
.. method:: Resource.name
.. method:: Resource.description
.. method:: Resource.default_emitter
.. method:: Resource.default_parser
.. method:: Resource.emitted_media_types
.. method:: Resource.parsed_media_types
:class:`Resource` reserved form and query parameters
----------------------------------------------------
.. attribute:: Resource.ACCEPT_QUERY_PARAM
If set, allows the default `Accept:` header content negotiation to be bypassed by setting the requested media type in a query parameter on the URL. This can be useful if it is necessary to be able to hyperlink to a given format on the Resource using standard HTML.
Set to None to disable, or to another string value to use another name for the reserved URL query parameter.
Default: ``"_accept"``
.. attribute:: Resource.METHOD_PARAM
If set, allows for PUT and DELETE requests to be tunneled on form POST operations, by setting a (typically hidden) form field with the method name. This allows standard HTML forms to perform method requests which would otherwise `not be supported <http://dev.w3.org/html5/spec/Overview.html#attr-fs-method>`_
Set to None to disable, or to another string value to use another name for the reserved form field.
Default: ``"_method"``
.. attribute:: Resource.CONTENTTYPE_PARAM
Used together with :attr:`CONTENT_PARAM`.
If set, allows for arbitrary content types to be tunneled on form POST operations, by setting a form field with the content type. This allows standard HTML forms to perform requests with content types other those `supported by default <http://dev.w3.org/html5/spec/Overview.html#attr-fs-enctype>`_ (ie. `application/x-www-form-urlencoded`, `multipart/form-data`, and `text-plain`)
Set to None to disable, or to another string value to use another name for the reserved form field.
Default: ``"_contenttype"``
.. attribute:: Resource.CONTENT_PARAM
Used together with :attr:`CONTENTTYPE_PARAM`.
Set to None to disable, or to another string value to use another name for the reserved form field.
Default: ``"_content"``
.. attribute:: Resource.CSRF_PARAM
The name used in Django's (typically hidden) form field for `CSRF Protection <http://docs.djangoproject.com/en/dev/ref/contrib/csrf/>`_.
Setting to None does not disable Django's CSRF middleware, but it does mean that the field name will not be treated as reserved by FlyWheel, so for example the default :class:`FormParser` will return fields with this as part of the request content, rather than ignoring them.
Default:: ``"csrfmiddlewaretoken"``
reserved params
internal methods
.. automodule:: resources
:members: