diff --git a/djangorestframework/authentication.py b/djangorestframework/authentication.py index b0ba41aae..1c5c832f3 100644 --- a/djangorestframework/authentication.py +++ b/djangorestframework/authentication.py @@ -1,10 +1,10 @@ """ -The ``authentication`` module provides a set of pluggable authentication classes. +The :mod:`authentication` module provides a set of pluggable authentication classes. -Authentication behavior is provided by adding the ``AuthMixin`` class to a ``View`` . +Authentication behavior is provided by mixing the :class:`mixins.AuthMixin` class into a :class:`View` class. The set of authentication methods which are used is then specified by setting the -``authentication`` attribute on the ``View`` class, and listing a set of authentication classes. +:attr:`authentication` attribute on the :class:`View` class, and listing a set of authentication classes. """ from django.contrib.auth import authenticate @@ -26,24 +26,23 @@ class BaseAuthenticaton(object): def __init__(self, view): """ - Authentication classes are always passed the current view on creation. + :param view: :class:`Authentication` classes are always passed the current view on creation. """ self.view = view def authenticate(self, request): """ - Authenticate the request and return a ``User`` instance or None. (*) - - This function must be overridden to be implemented. - - (*) The authentication context _will_ typically be a ``User`` object, - but it need not be. It can be any user-like object so long as the - permissions classes on the view can handle the object and use - it to determine if the request has the required permissions or not. - - This can be an important distinction if you're implementing some token - based authentication mechanism, where the authentication context - may be more involved than simply mapping to a ``User``. + :param request: Request to be authenticated + :rtype: :obj:`User` or None [*]_ + + .. [*] The authentication context *will* typically be a :obj:`User`, + but it need not be. It can be any user-like object so long as the + permissions classes on the view can handle the object and use + it to determine if the request has the required permissions or not. + + This can be an important distinction if you're implementing some token + based authentication mechanism, where the authentication context + may be more involved than simply mapping to a :obj:`User`. """ return None @@ -54,6 +53,10 @@ class BasicAuthenticaton(BaseAuthenticaton): """ def authenticate(self, request): + """ + Returns a :obj:`User` if a correct username and password have been supplied + using HTTP Basic authentication. Otherwise returns `None`. + """ from django.utils.encoding import smart_unicode, DjangoUnicodeDecodeError if 'HTTP_AUTHORIZATION' in request.META: @@ -81,6 +84,9 @@ class UserLoggedInAuthenticaton(BaseAuthenticaton): """ def authenticate(self, request): + """ + Returns a :obj:`User` if the request session currently has a logged in user, otherwise `None`. + """ # TODO: Switch this back to request.POST, and let FormParser/MultiPartParser deal with the consequences. if getattr(request, 'user', None) and request.user.is_active: # If this is a POST request we enforce CSRF validation. diff --git a/djangorestframework/mixins.py b/djangorestframework/mixins.py index 278d4d4da..e101b7883 100644 --- a/djangorestframework/mixins.py +++ b/djangorestframework/mixins.py @@ -408,28 +408,6 @@ class AuthMixin(object): permission.check_permission(user) -########## - -class InstanceMixin(object): - """ - Mixin class that is used to identify a view class as being the canonical identifier - for the resources it is mapped too. - """ - - @classmethod - def as_view(cls, **initkwargs): - """ - Store the callable object on the resource class that has been associated with this view. - """ - view = super(InstanceMixin, cls).as_view(**initkwargs) - if 'resource' in initkwargs: - # We do a little dance when we store the view callable... - # we need to store it wrapped in a 1-tuple, so that inspect will treat it - # as a function when we later look it up (rather than turning it into a method). - # This makes sure our URL reversing works ok. - initkwargs['resource'].view_callable = (view,) - return view - ########## Resource Mixin ########## class ResourceMixin(object): @@ -449,6 +427,9 @@ class ResourceMixin(object): @property def CONTENT(self): + """ + Returns the cleaned, validated request content. + """ if not hasattr(self, '_content'): self._content = self.validate_request(self.DATA, self.FILES) return self._content @@ -474,6 +455,28 @@ class ResourceMixin(object): +########## + +class InstanceMixin(object): + """ + Mixin class that is used to identify a view class as being the canonical identifier + for the resources it is mapped too. + """ + + @classmethod + def as_view(cls, **initkwargs): + """ + Store the callable object on the resource class that has been associated with this view. + """ + view = super(InstanceMixin, cls).as_view(**initkwargs) + if 'resource' in initkwargs: + # We do a little dance when we store the view callable... + # we need to store it wrapped in a 1-tuple, so that inspect will treat it + # as a function when we later look it up (rather than turning it into a method). + # This makes sure our URL reversing works ok. + initkwargs['resource'].view_callable = (view,) + return view + ########## Model Mixins ########## diff --git a/djangorestframework/views.py b/djangorestframework/views.py index 2e7e8418a..81567e687 100644 --- a/djangorestframework/views.py +++ b/djangorestframework/views.py @@ -11,7 +11,7 @@ __all__ = ( 'BaseView', 'ModelView', 'InstanceModelView', - 'ListOrModelView', + 'ListModelView', 'ListOrCreateModelView' ) @@ -131,7 +131,3 @@ class ListModelView(ListModelMixin, ModelView): class ListOrCreateModelView(ListModelMixin, CreateModelMixin, ModelView): """A view which provides default operations for list and create, against a model in the database.""" pass - - - - diff --git a/docs/conf.py b/docs/conf.py index 1a87b0245..503b40597 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,6 +60,7 @@ version = '0.1' release = '0.1' autodoc_member_order='bysource' + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None diff --git a/docs/examples/blogpost.rst b/docs/examples/blogpost.rst index 07f7cbc56..9d762f528 100644 --- a/docs/examples/blogpost.rst +++ b/docs/examples/blogpost.rst @@ -27,7 +27,7 @@ Creating the resources Once we have some existing models there's very little we need to do to create the corresponding resources. We simply create a base resource and an instance resource for each model we're working with. django-rest-framework will provide the default operations on the resources all the usual input validation that Django's models can give us for free. -``views.py`` +#``views.py`` -.. include:: ../../examples/blogpost/views.py - :literal: \ No newline at end of file +#.. include:: ../../examples/blogpost/views.py +# :literal: \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 4da2da1cb..3b4e9c49e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,7 +18,7 @@ Features: * Automatically provides an awesome Django admin style `browse-able self-documenting API `_. * Clean, simple, views for Resources, using Django's new `class based views `_. * Support for ModelResources with out-of-the-box default implementations and input validation. -* Pluggable :mod:`.emitters`, :mod:`parsers`, :mod:`validators` and :mod:`authenticators` - Easy to customise. +* Pluggable :mod:`.parsers`, :mod:`renderers`, :mod:`authentication` and :mod:`permissions` - Easy to customise. * Content type negotiation using HTTP Accept headers. * Optional support for forms as input validation. * Modular architecture - MixIn classes can be used without requiring the :class:`.Resource` or :class:`.ModelResource` classes. @@ -36,7 +36,8 @@ Resources Any and all questions, thoughts, bug reports and contributions are *hugely appreciated*. -We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking! (See: `Bitbucket `_, `GitHub `_) +We'd like for this to be a real community driven effort, so come say hi, get involved, and get forking! (See: `Forking a Bitbucket Repository +`_, or `Fork A GitHub Repo `_) Requirements ------------ @@ -139,14 +140,16 @@ Library Reference .. toctree:: :maxdepth: 1 - library/resource - library/modelresource - library/emitters + library/authentication + library/compat + library/mixins library/parsers - library/authenticators - library/validators + library/permissions + library/renderers + library/resource library/response library/status + library/views Examples Reference ------------------ diff --git a/docs/library/authentication.rst b/docs/library/authentication.rst new file mode 100644 index 000000000..d159f6054 --- /dev/null +++ b/docs/library/authentication.rst @@ -0,0 +1,5 @@ +:mod:`authentication` +===================== + +.. automodule:: authentication + :members: diff --git a/docs/library/authenticators.rst b/docs/library/authenticators.rst deleted file mode 100644 index 407339f78..000000000 --- a/docs/library/authenticators.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`authenticators` -===================== - -.. automodule:: authenticators - :members: diff --git a/docs/library/compat.rst b/docs/library/compat.rst new file mode 100644 index 000000000..93fb081a0 --- /dev/null +++ b/docs/library/compat.rst @@ -0,0 +1,5 @@ +:mod:`compat` +===================== + +.. automodule:: compat + :members: diff --git a/docs/library/emitters.rst b/docs/library/emitters.rst deleted file mode 100644 index 590ace0fa..000000000 --- a/docs/library/emitters.rst +++ /dev/null @@ -1,7 +0,0 @@ -:mod:`emitters` -=============== - -The emitters module provides a set of emitters that can be plugged in to a :class:`.Resource`. An emitter is responsible for taking the output of a and serializing it to a given media type. A :class:`.Resource` can have a number of emitters, allow the same content to be serialized in a number of different formats depending on the requesting client's preferences, as specified in the HTTP Request's Accept header. - -.. automodule:: emitters - :members: diff --git a/docs/library/mixins.rst b/docs/library/mixins.rst new file mode 100644 index 000000000..04bf66b06 --- /dev/null +++ b/docs/library/mixins.rst @@ -0,0 +1,5 @@ +:mod:`mixins` +===================== + +.. automodule:: mixins + :members: diff --git a/docs/library/modelresource.rst b/docs/library/modelresource.rst deleted file mode 100644 index af7609442..000000000 --- a/docs/library/modelresource.rst +++ /dev/null @@ -1,9 +0,0 @@ -:mod:`modelresource` -==================== - -.. note:: - - TODO - document this module properly - -.. automodule:: modelresource - :members: diff --git a/docs/library/permissions.rst b/docs/library/permissions.rst new file mode 100644 index 000000000..c694d639a --- /dev/null +++ b/docs/library/permissions.rst @@ -0,0 +1,5 @@ +:mod:`permissions` +===================== + +.. automodule:: permissions + :members: diff --git a/docs/library/renderers.rst b/docs/library/renderers.rst new file mode 100644 index 000000000..a9e729316 --- /dev/null +++ b/docs/library/renderers.rst @@ -0,0 +1,10 @@ +:mod:`renderers` +================ + +The renderers module provides a set of renderers that can be plugged in to a :class:`.Resource`. +A renderer is responsible for taking the output of a View and serializing it to a given media type. +A :class:`.Resource` can have a number of renderers, allow the same content to be serialized in a number +of different formats depending on the requesting client's preferences, as specified in the HTTP Request's Accept header. + +.. automodule:: renderers + :members: diff --git a/docs/library/validators.rst b/docs/library/validators.rst deleted file mode 100644 index 5d8b1dd79..000000000 --- a/docs/library/validators.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`validators` -================= - -.. automodule:: validators - :members: diff --git a/docs/library/views.rst b/docs/library/views.rst new file mode 100644 index 000000000..329b487b7 --- /dev/null +++ b/docs/library/views.rst @@ -0,0 +1,5 @@ +:mod:`views` +===================== + +.. automodule:: views + :members: