Metadata-Version: 1.1
Name: djoser
Version: 0.0.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|
        
        REST version of `Django <https://www.djangoproject.com/>`__
        authentication system. **djoser** is set of `Django Rest
        Framework <http://www.django-rest-framework.org/>`__ views to handle
        such things as registration, login and password reset. 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.
        
        Available endpoints:
        
        -  ``/me``
        -  ``/register``
        -  ``/login``
        -  ``/activate``
        -  ``/{{ User.USERNAME_FIELD }}``
        -  ``/password``
        -  ``/password/reset``
        -  ``/password/reset/confirm``
        
        Supported Python versions:
        
        -  Python 2.7
        -  Python 3.4
        
        Supported Django versions:
        
        -  Django 1.5
        -  Django 1.6
        -  Django 1.7
        
        Installation
        ------------
        
        Use ``pip``:
        
        ::
        
            $ pip install djoser
        
        Usage
        -----
        
        Configure ``INSTALLED_APPS``:
        
        .. code:: python
        
            INSTALLED_APPS = (
                'django.contrib.auth',
                (...), 
                'rest_framework',
                'rest_framework.authtoken',
                'djoser',
                (...), 
            )
        
        Configure ``urls.py``:
        
        .. code:: python
        
            urlpatterns = patterns('',
                (...),
                url(r'^auth/', include('djoser.urls')),
            )
        
        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}',
                'LOGIN_AFTER_ACTIVATION': True,
                'SEND_ACTIVATION_EMAIL': True,
            }
        
        Check `settings <#settings>`__ section for more info.
        
        Endpoints
        ---------
        
        User
        ~~~~
        
        URL: ``/me``
        
        Methods: ``GET``, ``PUT``
        
        ``PUT`` request data:
        
        -  ``{{ User.REQUIRED_FIELDS }}``
        
        ``PUT`` and ``GET`` response data:
        
        -  ``{{ User.USERNAME_FIELD }}``
        -  ``{{ User.REQUIRED_FIELDS }}``
        
        Use this endpoint to retrieve/update user.
        
        Register
        ~~~~~~~~
        
        URL: ``/register``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``{{ User.USERNAME_FIELD }}``
        -  ``{{ User.REQUIRED_FIELDS }}``
        -  ``password``
        
        ``POST`` response data:
        
        -  ``{{ User.USERNAME_FIELD }}``
        -  ``{{ User.REQUIRED_FIELDS }}``
        -  ``auth_token`` (if ``LOGIN_AFTER_ACTIVATION`` is ``True``)
        
        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.
        
        If ``LOGIN_AFTER_ACTIVATION`` is ``True``, you will receive
        authentication token within response.
        
        Login
        ~~~~~
        
        URL: ``/login``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``{{ User.USERNAME_FIELD }}``
        -  ``password``
        
        ``POST`` response data:
        
        -  ``auth_token``
        
        Use this endpoint to obtain user `authentication
        token <http://www.django-rest-framework.org/api-guide/authentication#tokenauthentication>`__.
        
        Activate
        ~~~~~~~~
        
        URL: ``/activate``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``uid``
        -  ``token``
        
        ``POST`` response data:
        
        -  ``auth_token`` (if ``LOGIN_AFTER_ACTIVATION`` is ``True``)
        
        Use this endpoint to activate user account.
        
        Set username
        ~~~~~~~~~~~~
        
        URL: ``/{{ User.USERNAME_FIELD }}``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``new_{{ User.USERNAME_FIELD }}``
        -  ``re_new_{{ User.USERNAME_FIELD }}`` (if ``SET_USERNAME_RETYPE`` is
           ``True``)
        -  ``current_password``
        
        Use this endpoint to change user username (``USERNAME_FIELD``).
        
        Set password
        ~~~~~~~~~~~~
        
        URL: ``/password``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``new_password``
        -  ``re_new_password`` (if ``SET_PASSWORD_RETYPE`` is ``True``)
        -  ``current_password``
        
        Use this endpoint to change user password.
        
        Reset password
        ~~~~~~~~~~~~~~
        
        URL: ``/password/reset``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``email``
        
        Use this endpoint to send email to user with password reset link. You
        have to setup ``DOMAIN``, ``SITE_NAME``, ``PASSWORD_RESET_CONFIRM_URL``.
        
        Reset password confirmation
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        URL: ``/password/reset/confirm``
        
        Methods: ``POST``
        
        ``POST`` request data:
        
        -  ``uid``
        -  ``token``
        -  ``new_password``
        -  ``re_new_password`` (if ``PASSWORD_RESET_CONFIRM_RETYPE`` is
           ``True``)
        
        Use this endpoint to finish reset password process.
        
        Settings
        --------
        
        ``LOGIN_AFTER_REGISTRATION``
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        If ``True``, register endpoint will return ``auth_token`` within
        response.
        
        Default: ``False``
        
        ``DOMAIN``
        ^^^^^^^^^^
        
        Domain of your frontend app. Default: ``''``.
        
        ``SITE_NAME``
        ^^^^^^^^^^^^^
        
        Name of your frontend app. Default: ``''``.
        
        ``PASSWORD_RESET_CONFIRM_URL``
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        URL to your frontend password reset page. It should containt ``{uid}``
        and ``{token}`` placeholders, e.g. ``#/password-reset/{uid}/{token}``.
        Default: ``''``.
        
        ``SEND_ACTIVATION_EMAIL``
        ^^^^^^^^^^^^^^^^^^^^^^^^^
        
        If ``True``, register endpoint will send activation email to user.
        
        ``ACTIVATION_URL``
        ^^^^^^^^^^^^^^^^^^
        
        URL to your frontend activation page. It should containt ``{uid}`` and
        ``{token}`` placeholders, e.g. ``#/activate/{uid}/{token}``. Default:
        ``''``.
        
        ``LOGIN_AFTER_ACTIVATION``
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        If ``True``, activate endpoint will return ``auth_token`` within
        response.
        
        Default: ``False``
        
        ``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, to validate password equality.
        
        Default: ``False``
        
        Emails
        ------
        
        There are few email templates which you could 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``
        
        Customization
        -------------
        
        If you need to override some ``djoser`` behaviour, you could define your
        custom view/serializer.
        
        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_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>`__
        
        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
        
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
