<commit_before>Customizing Redirects and Callbacks
====================================

django-all-access provides default views/urls for authentication. These are built
from Django's `class based views <https://docs.djangoproject.com/en/1.4/topics/class-based-views/>`_
making them easy to extend or override the default behavior in your project.


OAuthRedirect View
----------------------

The initial step for authenticating with any OAuth provider is redirecting the
user to the provider's website. The :py:class:`OAuthRedirect` view extends from the
`RedirectView <https://docs.djangoproject.com/en/1.4/ref/class-based-views/#redirectview>`_
By default it is mapped to the ``allaccess-login`` url name. This view takes one
keyword argument from the url pattern ``provider`` which corresponds to the ``Provider.name``
for an enabled provider. If no enabled provider is found for the name then this view
will return a 404.

.. class:: OAuthRedirect()

    .. attribute:: client_class
    .. versionadded:: 0.5

        Used to change the :py:class:`BaseOAuthClient` used by the view. See
        :py:method:`OAuthRedirect.get_client` for more details.

    .. method:: get_client(provider)
    .. versionadded:: 0.5
        
        Here you can override the OAuth client class which is used to generate the
        redirect url. Another use case is to disable the enforcement of the OAuth 2.0
        ``state`` parameter for providers which don't support it. If you are using
        the view for a single provider it would be easiest to set the 
        :py:attr:`OAuthRedirect.client_class` attribute on the class instead.

        You should be sure to use the same client class for the callback view as well.

    .. method:: get_redirect_url(**kwargs)

        This method is original defined by the RedirectView. The redirect url is
        constructed from the ``Provider.authorization_url`` along with the necessary
        parameters to match the OAuth specifications. You should not need to override
        this method in your application.

    .. method:: get_additional_parameters(provider)

        Here you can return additional parameters for the authorization request. By
        default this returns ``{}``. A common usage for overriding this method is
        to request additional permissions for the authorization. There is no
        standard for additional permissions in the OAuth 1.0 specification. For
        an OAuth 2.0 provider this is done with the ``scope`` parameter.

    .. method:: get_callback_url(provider)

        This returns the url which the remote provider should return the user after
        authentication. It is called by :py:meth:`OAuthRedirect.get_redirect_url` to construct 
        the appropriate redirect url. By default the reverses the ``allaccess-callback``
        url name with the passed provider name.

        You may want to override this method in your application if you wish to have
        a custom callback for a given provider or a different callback for login vs
        registration or a different callback for an authenticated user associating a
        new provider with their account.


OAuthCallback View
----------------------

After the user has authenticated with the remote provider or denied access to your application
request, they are returned to callback specifed in the initial redirect. :py:class:`OAuthCallback`
defines the default behaviour on this callback. This view extends from the base
`View <https://docs.djangoproject.com/en/1.4/ref/class-based-views/#view>`_ class.
By default it is mapped to the ``allaccess-callback`` url name. Similar to the :py:class:`OAuthRedirect` view, 
this view takes one keyword argument ``provider`` which corresponds to the ``Provider.name`` 
for an enabled provider. If no enabled provider is found for the name then this view will return a 404.

.. class:: OAuthCallback()

    .. attribute:: client_class
    .. versionadded:: 0.5

        Used to change the :py:class:`BaseOAuthClient` used by the view. See
        :py:method:`OAuthCallback.get_client` for more details.

    .. method:: get_callback_url(provider)

        This returns the callback url specified in the initial redirect if it is
        different than the current ``request.path``. By default the callback url will be the same
        and this view will return ``None``. You will most likely not need to change this
        in your project.

    .. method:: get_client(provider)
    .. versionadded:: 0.5
        
        Here you can override the OAuth client class which is used to fetch the access
        token and user information. Another use case is to disable the enforcement of
        the OAuth 2.0 ``state`` parameter for providers which don't support it. If you 
        are using the view for a single provider it would be easiest to set the 
        :py:attr:`OAuthCallback.client_class` attribute on the class instead.

        You should be sure to use the same client class for the redirect view as well.

    .. method:: get_error_redirect(provider, reason)
        
        Returns the url to send the user in the case of an authentication failure. The
        ``reason`` is a brief text description of the problem. By default this will return
        the user to the original login url as defined by the ``LOGIN_URL`` setting.

    .. method:: get_login_redirect(provider, user, access, new=False)

        You can use this to customize the url to send the user on a successful authentication.
        By default this will be the ``LOGIN_REDIRECT_URL`` setting. The ``new`` parameter
        is there to indicate if this was a newly created or a previously existing user.

    .. method:: get_or_create_user(provider, access, info)
<commit_msg>Reorder version added infomation in the docs.<commit_after>Customizing Redirects and Callbacks
====================================

django-all-access provides default views/urls for authentication. These are built
from Django's `class based views <https://docs.djangoproject.com/en/1.4/topics/class-based-views/>`_
making them easy to extend or override the default behavior in your project.


OAuthRedirect View
----------------------

The initial step for authenticating with any OAuth provider is redirecting the
user to the provider's website. The :py:class:`OAuthRedirect` view extends from the
`RedirectView <https://docs.djangoproject.com/en/1.4/ref/class-based-views/#redirectview>`_
By default it is mapped to the ``allaccess-login`` url name. This view takes one
keyword argument from the url pattern ``provider`` which corresponds to the ``Provider.name``
for an enabled provider. If no enabled provider is found for the name then this view
will return a 404.

.. class:: OAuthRedirect()

    .. versionadded:: 0.5
    .. attribute:: client_class
    

        Used to change the :py:class:`BaseOAuthClient` used by the view. See
        :py:meth:`OAuthRedirect.get_client` for more details.

    .. versionadded:: 0.5
    .. method:: get_client(provider)
        
        Here you can override the OAuth client class which is used to generate the
        redirect url. Another use case is to disable the enforcement of the OAuth 2.0
        ``state`` parameter for providers which don't support it. If you are using
        the view for a single provider it would be easiest to set the 
        :py:attr:`OAuthRedirect.client_class` attribute on the class instead.

        You should be sure to use the same client class for the callback view as well.

    .. method:: get_redirect_url(**kwargs)

        This method is original defined by the RedirectView. The redirect url is
        constructed from the ``Provider.authorization_url`` along with the necessary
        parameters to match the OAuth specifications. You should not need to override
        this method in your application.

    .. method:: get_additional_parameters(provider)

        Here you can return additional parameters for the authorization request. By
        default this returns ``{}``. A common usage for overriding this method is
        to request additional permissions for the authorization. There is no
        standard for additional permissions in the OAuth 1.0 specification. For
        an OAuth 2.0 provider this is done with the ``scope`` parameter.

    .. method:: get_callback_url(provider)

        This returns the url which the remote provider should return the user after
        authentication. It is called by :py:meth:`OAuthRedirect.get_redirect_url` to construct 
        the appropriate redirect url. By default the reverses the ``allaccess-callback``
        url name with the passed provider name.

        You may want to override this method in your application if you wish to have
        a custom callback for a given provider or a different callback for login vs
        registration or a different callback for an authenticated user associating a
        new provider with their account.


OAuthCallback View
----------------------

After the user has authenticated with the remote provider or denied access to your application
request, they are returned to callback specifed in the initial redirect. :py:class:`OAuthCallback`
defines the default behaviour on this callback. This view extends from the base
`View <https://docs.djangoproject.com/en/1.4/ref/class-based-views/#view>`_ class.
By default it is mapped to the ``allaccess-callback`` url name. Similar to the :py:class:`OAuthRedirect` view, 
this view takes one keyword argument ``provider`` which corresponds to the ``Provider.name`` 
for an enabled provider. If no enabled provider is found for the name then this view will return a 404.

.. class:: OAuthCallback()

    .. versionadded:: 0.5
    .. attribute:: client_class
    

        Used to change the :py:class:`BaseOAuthClient` used by the view. See
        :py:meth:`OAuthCallback.get_client` for more details.

    .. method:: get_callback_url(provider)

        This returns the callback url specified in the initial redirect if it is
        different than the current ``request.path``. By default the callback url will be the same
        and this view will return ``None``. You will most likely not need to change this
        in your project.

    .. versionadded:: 0.5
    .. method:: get_client(provider)
        
        Here you can override the OAuth client class which is used to fetch the access
        token and user information. Another use case is to disable the enforcement of
        the OAuth 2.0 ``state`` parameter for providers which don't support it. If you 
        are using the view for a single provider it would be easiest to set the 
        :py:attr:`OAuthCallback.client_class` attribute on the class instead.

        You should be sure to use the same client class for the redirect view as well.

    .. method:: get_error_redirect(provider, reason)
        
        Returns the url to send the user in the case of an authentication failure. The
        ``reason`` is a brief text description of the problem. By default this will return
        the user to the original login url as defined by the ``LOGIN_URL`` setting.

    .. method:: get_login_redirect(provider, user, access, new=False)

        You can use this to customize the url to send the user on a successful authentication.
        By default this will be the ``LOGIN_REDIRECT_URL`` setting. The ``new`` parameter
        is there to indicate if this was a newly created or a previously existing user.

    .. method:: get_or_create_user(provider, access, info)

{'fraction_non_alphanumeric': 0.07492222606291048, 'fraction_numerical': 0.004839267196681645, 'mean_word_length': 3.136168691922802, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1647398', 'n_tokens_mistral': 2879, 'n_tokens_neox': 2749, 'n_words': 1446}