Metadata-Version: 1.1
Name: djoser
Version: 0.5.2
Summary: REST version of Django authentication system.
Home-page: https://github.com/sunscrapers/djoser
Author: SUNSCRAPERS
Author-email: info@sunscrapers.com
License: MIT
Description: djoser
        ======
        
        |Build Status| |Coverage Status|
        
        REST implementation of `Django <https://www.djangoproject.com/>`__
        authentication system. **Djoser** library provides a set of `Django Rest
        Framework <http://www.django-rest-framework.org/>`__ views to handle
        basic actions such as registration, login, logout, password reset and
        account activation. It works with `custom user
        model <https://docs.djangoproject.com/en/dev/topics/auth/customizing/>`__.
        
        Instead of reusing Django code (e.g. ``PasswordResetForm``), we
        reimplemented few things to fit better into `Single Page
        App <http://en.wikipedia.org/wiki/Single-page_application>`__
        architecture.
        
        Developed by `SUNSCRAPERS <http://sunscrapers.com/>`__ with passion &
        patience.
        
        Features
        --------
        
        Here is a list of supported authentication backends:
        
        -  `HTTP Basic
           Auth <http://www.django-rest-framework.org/api-guide/authentication/#basicauthentication>`__
           (Default)
        -  `Token based authentication from Django Rest
           Framework <http://www.django-rest-framework.org/api-guide/authentication#tokenauthentication>`__
        
        Available endpoints:
        
        -  ``/me/``
        -  ``/register/``
        -  ``/login/`` (token based authentication)
        -  ``/logout/`` (token based authentication)
        -  ``/activate/``
        -  ``/{{ User.USERNAME_FIELD }}/``
        -  ``/password/``
        -  ``/password/reset/``
        -  ``/password/reset/confirm/``
        
        Supported Python versions:
        
        -  Python 2.7
        -  Python 3.4
        -  Python 3.5
        
        Supported Django versions:
        
        -  Django 1.7
        -  Django 1.8
        -  Django 1.9
        -  Django 1.10
        
        Supported Django Rest Framework versions:
        
        -  Django Rest Framework 3.x
        
        For Django Rest Framework 2.4 support check `djoser
        0.3.2 <https://github.com/sunscrapers/djoser/tree/0.3.2>`__.
        
        Installation
        ------------
        
        Use ``pip``:
        
        ::
        
            $ pip install djoser
        
        Quick Start
        -----------
        
        Configure ``INSTALLED_APPS``:
        
        .. code:: python
        
            INSTALLED_APPS = (
                'django.contrib.auth',
                (...),
                'rest_framework',
                'djoser',
                (...),
            )
        
        Configure ``urls.py``:
        
        .. code:: python
        
            urlpatterns = patterns('',
                (...),
                url(r'^auth/', include('djoser.urls')),
            )
        
        HTTP Basic Auth strategy is assumed by default as Django Rest Framework
        does it. However you may want to set it explicitly:
        
        .. code:: python
        
            REST_FRAMEWORK = {
                'DEFAULT_AUTHENTICATION_CLASSES': (
                    'rest_framework.authentication.BasicAuthentication',
                ),
            }
        
        Run migrations - this step will create tables for ``auth`` app:
        
        ::
        
            $ ./manage.py migrate
        
        Customizing authentication backend
        ----------------------------------
        
        Token Based Authentication
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Add ``'rest_framework.authtoken'`` to ``INSTALLED_APPS``:
        
        .. code:: python
        
            INSTALLED_APPS = (
                'django.contrib.auth',
                (...),
                'rest_framework',
                'rest_framework.authtoken',
                'djoser',
                (...),
            )
        
        Configure ``urls.py``. Pay attention to ``djoser.url.authtoken`` module
        path.
        
        .. code:: python
        
            urlpatterns = patterns('',
                (...),
                url(r'^auth/', include('djoser.urls.authtoken')),
            )
        
        Set ``TokenAuthentication`` as default Django Rest Framework
        authentication strategy:
        
        .. code:: python
        
            REST_FRAMEWORK = {
                'DEFAULT_AUTHENTICATION_CLASSES': (
                    'rest_framework.authentication.TokenAuthentication',
                ),
            }
        
        Run migrations - this step will create tables for ``auth`` and
        ``authtoken`` apps:
        
        ::
        
            $ ./manage.py migrate
        
        JSON Web Token Authentication
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        ``djoser`` does not provide support for JSON web token authentication
        out of the box but can be enabled by using a library like
        `djangorestframework-jwt <https://github.com/GetBlimp/django-rest-framework-jwt>`__.
        
        You simply need to route correctly in your ``settings.ROOT_URLCONF``. An
        example would be:
        
        ::
        
            import rest_framework_jwt.views
            import djoser.views
        
            urlpatterns = [
                url(r'^auth/login', rest_framework_jwt.views.obtain_jwt_token),  # using JSON web token
                url(r'^auth/register', djoser.views.RegistrationView.as_view()),
                url(r'^auth/password/reset', djoser.views.PasswordResetView.as_view()),
                url(r'^auth/password/reset/confirm', djoser.views.PasswordResetConfirmView.as_view()),
                ...
            ]
        
        Settings
        --------
        
        Optionally add ``DJOSER`` settings:
        
        .. code:: python
        
            DJOSER = {
                'DOMAIN': 'frontend.com',
                'SITE_NAME': 'Frontend',
                'PASSWORD_RESET_CONFIRM_URL': '#/password/reset/confirm/{uid}/{token}',
                'ACTIVATION_URL': '#/activate/{uid}/{token}',
                'SEND_ACTIVATION_EMAIL': True,
                'PASSWORD_VALIDATORS': [],
                'SERIALIZERS': {},
            }
        
        Check "Settings" section for more info.
        
        Endpoints
        ---------
        
        User
        ~~~~
        
        Use this endpoint to retrieve/update user.
        
        ``GET``
        ^^^^^^^
        
        URL: ``/me/``
        
        Retrieve user.
        
        -  **response**
        
           -  status: ``HTTP_200_OK`` (success)
        
           -  data:
        
              ``{{ User.USERNAME_FIELD }}``
        
              ``{{ User._meta.pk.name }}``
        
              ``{{ User.REQUIRED_FIELDS }}``
        
        ``PUT``
        ^^^^^^^
        
        URL: ``/me/``
        
        Update user.
        
        -  **request**
        
           -  data:
        
              ``{{ User.REQUIRED_FIELDS }}``
        
        -  **response**
        
           -  status: ``HTTP_200_OK`` (success)
        
           -  data:
        
              ``{{ User.USERNAME_FIELD }}``
        
              ``{{ User._meta.pk.name }}``
        
              ``{{ User.REQUIRED_FIELDS }}``
        
        Register
        ~~~~~~~~
        
        Use this endpoint to register new user. Your user model manager should
        implement
        `create\_user <https://docs.djangoproject.com/en/dev/ref/contrib/auth/#django.contrib.auth.models.UserManager.create_user>`__
        method and have
        `USERNAME\_FIELD <https://docs.djangoproject.com/en/dev/topics/auth/customizing/#django.contrib.auth.models.CustomUser.USERNAME_FIELD>`__
        and
        `REQUIRED\_FIELDS <https://docs.djangoproject.com/en/dev/topics/auth/customizing/#django.contrib.auth.models.CustomUser.REQUIRED_FIELDS>`__
        fields.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/register/``
        
        -  **request**
        
           -  data:
        
              ``{{ User.USERNAME_FIELD }}``
        
              ``{{ User.REQUIRED_FIELDS }}``
        
              ``password``
        
        -  **response**
        
           -  status: ``HTTP_201_CREATED`` (success)
        
           -  data:
        
              ``{{ User.USERNAME_FIELD }}``
        
              ``{{ User._meta.pk.name }}``
        
              ``{{ User.REQUIRED_FIELDS }}``
        
        Login
        ~~~~~
        
        Use this endpoint to obtain user `authentication
        token <http://www.django-rest-framework.org/api-guide/authentication#tokenauthentication>`__.
        This endpoint is available only if you are using token based
        authentication.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/login/``
        
        -  **request**
        
           -  data:
        
              ``{{ User.USERNAME_FIELD }}``
        
              ``password``
        
        -  **response**
        
           -  status: ``HTTP_200_OK`` (success)
        
           -  data:
        
              ``auth_token``
        
        Logout
        ~~~~~~
        
        Use this endpoint to logout user (remove user authentication token).
        This endpoint is available only if you are using token based
        authentication.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/logout/``
        
        -  **response**
        
           -  status: ``HTTP_204_NO_CONTENT`` (success)
        
        Activate
        ~~~~~~~~
        
        Use this endpoint to activate user account. This endpoint is not a URL
        which will be directly exposed to your users - you should provide site
        in your frontend application (configured by ``ACTIVATION_URL``) which
        will send ``POST`` request to activate endpoint.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/activate/``
        
        -  **request**
        
           -  data:
        
              ``uid``
        
              ``token``
        
        -  **response**
        
           -  status: ``HTTP_204_NO_CONTENT`` (success)
        
        Set username
        ~~~~~~~~~~~~
        
        Use this endpoint to change user username (``USERNAME_FIELD``).
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/{{ User.USERNAME_FIELD }}/``
        
        -  **request**
        
           -  data:
        
              ``new_{{ User.USERNAME_FIELD }}``
        
              ``re_new_{{ User.USERNAME_FIELD }}`` (if ``SET_USERNAME_RETYPE``
              is ``True``)
        
              ``current_password``
        
        -  **response**
        
           -  status: ``HTTP_204_NO_CONTENT`` (success)
        
        Set password
        ~~~~~~~~~~~~
        
        Use this endpoint to change user password.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/password/``
        
        -  **request**
        
           -  data:
        
              ``new_password``
        
              ``re_new_password`` (if ``SET_PASSWORD_RETYPE`` is ``True``)
        
              ``current_password``
        
        -  **response**
        
           -  status: ``HTTP_204_NO_CONTENT`` (success)
        
        Reset password
        ~~~~~~~~~~~~~~
        
        Use this endpoint to send email to user with password reset link. You
        have to setup ``PASSWORD_RESET_CONFIRM_URL``.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/password/reset/``
        
        -  **request**
        
           -  data:
        
              ``email``
        
        -  **response**
        
           -  status: ``HTTP_204_NO_CONTENT`` (success), if
              ``PASSWORD_RESET_SHOW_EMAIL_NOT_FOUND`` is ``False`` (default); or
           -  status: ``HTTP_400_BAD_REQUEST``, if
              ``PASSWORD_RESET_SHOW_EMAIL_NOT_FOUND`` is ``True`` and ``email``
              does not exists in the database.
        
        Reset password confirmation
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Use this endpoint to finish reset password process. This endpoint is not
        a URL which will be directly exposed to your users - you should provide
        site in your frontend application (configured by
        ``PASSWORD_RESET_CONFIRM_URL``) which will send ``POST`` request to
        reset password confirmation endpoint.
        
        ``POST``
        ^^^^^^^^
        
        URL: ``/password/reset/confirm/``
        
        -  **request**
        
           -  data:
        
              ``uid``
        
              ``token``
        
              ``new_password``
        
              ``re_new_password`` (if ``PASSWORD_RESET_CONFIRM_RETYPE`` is
              ``True``)
        
        -  **response**
        
           -  status: ``HTTP_204_NO_CONTENT`` (success)
        
        Settings
        --------
        
        DOMAIN
        ~~~~~~
        
        Domain of your frontend app. If not provided, domain of current site
        will be used.
        
        **Required**: ``False``
        
        SITE\_NAME
        ~~~~~~~~~~
        
        Name of your frontend app. If not provided, name of current site will be
        used.
        
        **Required**: ``False``
        
        PASSWORD\_RESET\_CONFIRM\_URL
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        URL to your frontend password reset page. It should contain ``{uid}``
        and ``{token}`` placeholders, e.g. ``#/password-reset/{uid}/{token}``.
        You should pass ``uid`` and ``token`` to reset password confirmation
        endpoint.
        
        **Required**: ``True``
        
        SEND\_ACTIVATION\_EMAIL
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, register endpoint will send activation email to user.
        
        **Default**: ``False``
        
        SEND\_CONFIRMATION\_EMAIL
        ~~~~~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, register or activation endpoint will send confirmation
        email to user.
        
        **Default**: ``False``
        
        ACTIVATION\_URL
        ~~~~~~~~~~~~~~~
        
        URL to your frontend activation page. It should contain ``{uid}`` and
        ``{token}`` placeholders, e.g. ``#/activate/{uid}/{token}``. You should
        pass ``uid`` and ``token`` to activation endpoint.
        
        **Required**: ``True``
        
        SET\_USERNAME\_RETYPE
        ~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, you need to pass ``re_new_{{ User.USERNAME_FIELD }}`` to
        ``/{{ User.USERNAME_FIELD }}/`` endpoint, to validate username equality.
        
        **Default**: ``False``
        
        SET\_PASSWORD\_RETYPE
        ~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, you need to pass ``re_new_password`` to ``/password/``
        endpoint, to validate password equality.
        
        **Default**: ``False``
        
        PASSWORD\_RESET\_CONFIRM\_RETYPE
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, you need to pass ``re_new_password`` to
        ``/password/reset/confirm/`` endpoint in order to validate password
        equality.
        
        **Default**: ``False``
        
        LOGOUT\_ON\_PASSWORD\_CHANGE
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, setting new password will logout the user.
        
        **Default**: ``False``
        
        PASSWORD\_RESET\_SHOW\_EMAIL\_NOT\_FOUND
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        If ``True``, posting a non-existent ``email`` to ``/password/reset/``
        will return a ``HTTP_400_BAD_REQUEST`` response with an
        ``EMAIL_NOT_FOUND`` error message ('User with given email does not
        exist.').
        
        If ``False`` (default), the ``/password/reset/`` endpoint will always
        return a ``HTTP_204_NO_CONTENT`` response.
        
        Please note that setting this to ``True`` will expose information
        whether an email is registered in the system.
        
        **Default**: ``False``
        
        PASSWORD\_VALIDATORS
        ~~~~~~~~~~~~~~~~~~~~
        
        List containing `REST Framework
        Validator <http://www.django-rest-framework.org/api-guide/validators/>`__
        functions. These validators are run on ``/register/`` and
        ``/password/reset/confirm/``.
        
        **Default**: ``[]``
        
        **Example**: ``[my_validator1, my_validator2]``
        
        SERIALIZERS
        ~~~~~~~~~~~
        
        This dictionary is used to update the defaults, so by providing, let's
        say, one key, all the others will still be used.
        
        **Examples**
        
        ::
        
            {
                'user': 'myapp.serializers.SpecialUserSerializer',
            }
        
        **Default**:
        
        ::
        
            {
                'activation': 'djoser.serializers.ActivationSerializer',
                'login': 'djoser.serializers.LoginSerializer',
                'password_reset': 'djoser.serializers.PasswordResetSerializer',
                'password_reset_confirm': 'djoser.serializers.PasswordResetConfirmSerializer',
                'password_reset_confirm_retype': 'djoser.serializers.PasswordResetConfirmRetypeSerializer',
                'set_password': 'djoser.serializers.SetPasswordSerializer',
                'set_password_retype': 'djoser.serializers.SetPasswordRetypeSerializer',
                'set_username': 'djoser.serializers.SetUsernameSerializer',
                'set_username_retype': 'djoser.serializers.SetUsernameRetypeSerializer',
                'user_registration': 'djoser.serializers.UserRegistrationSerializer',
                'user': 'djoser.serializers.UserSerializer',
                'token': 'djoser.serializers.TokenSerializer',
            }
        
        Emails
        ------
        
        There are few email templates which you may want to override:
        
        -  ``activation_email_body.txt``
        -  ``activation_email_subject.txt``
        -  ``password_reset_email_body.txt``
        -  ``password_reset_email_subject.txt``
        
        All of them have following context:
        
        -  ``user``
        -  ``domain``
        -  ``site_name``
        -  ``url``
        -  ``uid``
        -  ``token``
        -  ``protocol``
        
        Sample usage
        ------------
        
        We provide a standalone test app for you to start easily, see how
        everything works with basic settings. It might be useful before
        integrating **djoser** into your backend application.
        
        In this extremely short tutorial we are going to mimic the simplest
        flow: register user, log in and log out. We will also check resource
        access on each consecutive step. Let's go!
        
        -  Clone repository and install **djoser** to your virtualenv:
        
           ``$ git clone git@github.com:sunscrapers/djoser.git``
        
           ``$ cd djoser``
        
           ``$ pip install -e .``
        
        -  Go to the ``testproject`` directory, migrate the database and start
           the development server:
        
           ``$ cd testproject``
        
           ``$ ./manage.py migrate``
        
           ``$ ./manage.py runserver 8088``
        
        -  Register a new user:
        
           ``$ curl -X POST http://127.0.0.1:8088/auth/register/ --data 'username=djoser&password=djoser'``
        
           ``{"email": "", "username": "djoser", "id":1}``
        
           So far, so good. We have just created a new user using REST API.
        
        -  Let's access user's details:
        
           ``$ curl -X GET http://127.0.0.1:8088/auth/me/``
        
           ``{"detail": "Authentication credentials were not provided."}``
        
           As we can see, we cannot access user profile without logging in.
           Pretty obvious.
        
        -  Let's log in:
        
           ``curl -X POST http://127.0.0.1:8088/auth/login/ --data 'username=djoser&password=djoser'``
        
           ``{"auth_token": "b704c9fc3655635646356ac2950269f352ea1139"}``
        
           We have just obtained an authorization token that we may use later in
           order to retrieve specific resources.
        
        -  Let's access user's details again:
        
           ``$ curl -X GET http://127.0.0.1:8088/auth/me/``
        
           ``{"detail": "Authentication credentials were not provided."}``
        
           Access is still forbidden but let's offer the token we obtained:
        
           ``$ curl -X GET http://127.0.0.1:8088/auth/me/ -H 'Authorization: Token b704c9fc3655635646356ac2950269f352ea1139'``
        
           ``{"email": "", "username": "djoser", "id": 1}``
        
           Yay, it works!
        
        -  Now let's log out:
        
           ``curl -X POST http://127.0.0.1:8088/auth/logout/ -H 'Authorization: Token b704c9fc3655635646356ac2950269f352ea1139'``
        
           And try access user profile again:
        
           ``$ curl -X GET http://127.0.0.1:8088/auth/me/ -H 'Authorization: Token b704c9fc3655635646356ac2950269f352ea1139'``
        
           ``{"detail": "Invalid token"}``
        
           As we can see, user has been logged out successfully and the proper
           token has been removed.
        
        Customization
        -------------
        
        If you need to customize any serializer behaviour you can use the
        DJOSER['SERIALIZERS'] setting to use your own serializer classes in the
        built-in views. Or if you need to completely change the default djoser
        behaviour, you can always override djoser views with your own custom
        ones.
        
        Define custom ``urls`` instead of reusing ``djoser.urls``:
        
        .. code:: python
        
            urlpatterns = patterns('',
                (...),
                url(r'^register/$', views.CustomRegistrationView.as_view()),
            )
        
        Define custom view/serializer (inherit from one of ``djoser`` class) and
        override necessary method/field:
        
        .. code:: python
        
            class CustomRegistrationView(djoser.views.RegistrationView):
        
                def send_activation_email(self, *args, **kwargs):
                    your_custom_email_sender(*args, **kwargs)
        
        You could check ``djoser`` API in source code:
        
        -  `djoser.views <https://github.com/sunscrapers/djoser/blob/master/djoser/views.py>`__
        -  `djoser.serializers <https://github.com/sunscrapers/djoser/blob/master/djoser/serializers.py>`__
        
        Development
        -----------
        
        To start developing on **djoser**, clone the repository:
        
        ``$ git clone git@github.com:sunscrapers/djoser.git``
        
        In order to run the tests create virtualenv, go to repo directory and
        then:
        
        ``$ pip install -r requirements-test.txt``
        
        ``$ cd testproject``
        
        ``$ ./manage.py migrate``
        
        ``$ ./manage.py test``
        
        If you need to run tests against all supported Python and Django
        versions then invoke:
        
        ``$ pip install tox``
        
        ``$ tox``
        
        Similar projects
        ----------------
        
        List of projects related to Django, REST and authentication:
        
        -  `django-rest-auth <https://github.com/Tivix/django-rest-auth>`__
        -  `django-rest-framework-digestauth <https://github.com/juanriaza/django-rest-framework-digestauth>`__
        -  `django-oauth-toolkit <https://github.com/evonove/django-oauth-toolkit>`__
        -  `doac <https://github.com/Rediker-Software/doac>`__
        -  `django-rest-framework-jwt <https://github.com/GetBlimp/django-rest-framework-jwt>`__
        -  `django-rest-framework-httpsignature <https://github.com/etoccalino/django-rest-framework-httpsignature>`__
        -  `hawkrest <https://github.com/kumar303/hawkrest>`__
        
        .. |Build Status| image:: https://travis-ci.org/sunscrapers/djoser.svg?branch=master
           :target: https://travis-ci.org/sunscrapers/djoser
        .. |Coverage Status| image:: https://coveralls.io/repos/sunscrapers/djoser/badge.png?branch=master
           :target: https://coveralls.io/r/sunscrapers/djoser?branch=master
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
