<commit_before>Introduction
============

``django-lazysignup`` is a package designed to allow users to interact with a 
site as if they were authenticated users, but without signing up. At any time, 
they can convert their temporary user account to a real user account.

``django-lazysignup`` is beta software. Bug reports, patches and extensions
are welcomed. While this package is in beta, backwards-compatibility will be
maintained for a single point release and a DeprecationWarning issued.

Requirements
============

Tested on Django 1.2.x, though should work on Django 1.0 and later 
(although you  will need to customise one of the templates.) It requires 
``django.contrib.auth`` to be in the ``INSTALLED_APPS`` list.

Installation
============

django-lazysignup can be installed with your favourite package management tool
from PyPI::

  pip install django-lazysignup

Once that's done, you need to add ``lazysignup`` to your ``INSTALLED_APPS``. 
You will also need to add ``lazysignup``'s authentication backend to your 
site's ``AUTHENTICATION_BACKENDS`` setting::

  AUTHENTICATION_BACKENDS = (
    'django.contrib.auth.backends.ModelBackend',
    'lazysignup.backends.LazySignupBackend',
  )
  
If you are using Django prior to 1.2, you should override the 
``lazysignup/convert.html``  template to remove the ``{% csrf_token %}`` 
template tag. This may be handled more elegantly in a future release.

Finally, you need to add lazysignup to your URLConf, using something like
this::

  urlpatterns += (''
      (r'^convert/', include('lazysignup.urls')),
  )


Usage
=====

The package works by creating temporary user accounts based on a user's 
session key whenever a flagged view is requested. You can specify which
views trigger this behaviour using the ``lazysignup.decorators.allow_lazy_user``
decorator.

When an anonymous user requests such a view, a temporary user account will be 
created for them, and they will be logged in. The user account will have
an unusable password set, so that it can't be used to log in as a regular
user. Hence, the way to tell a regular use from a temporary user is to call
the ``user.has_usable_password()`` method. If this returns ``False``, then the
user is temporary. Note that ``user.is_anonymous()`` will return ``False`` 
and ``user.is_authenticated()`` will return ``True``.

A view is provided to allow such users to convert their temporary account into
a real user account by providing a username and a password.

A Django management command is provided to clear out stale, uncoverted user
accounts. 

The ``allow_lazy_user`` decorator
---------------------------------

Use this decorator to indicate that accessing the view should cause anonymous
users to have temporary accounts created for them. 

For example::

  from django.http import HttpResponse
  from lazysignup.decorators import allow_lazy_user<commit_msg>Add note to docs on providing a custom clean script.<commit_after>Introduction
============

``django-lazysignup`` is a package designed to allow users to interact with a 
site as if they were authenticated users, but without signing up. At any time, 
they can convert their temporary user account to a real user account.

``django-lazysignup`` is beta software. Bug reports, patches and extensions
are welcomed. While this package is in beta, backwards-compatibility will be
maintained for a single point release and a DeprecationWarning issued.

Requirements
============

Tested on Django 1.2.x, though should work on Django 1.0 and later 
(although you  will need to customise one of the templates.) It requires 
``django.contrib.auth`` to be in the ``INSTALLED_APPS`` list.

Installation
============

django-lazysignup can be installed with your favourite package management tool
from PyPI::

  pip install django-lazysignup

Once that's done, you need to add ``lazysignup`` to your ``INSTALLED_APPS``. 
You will also need to add ``lazysignup``'s authentication backend to your 
site's ``AUTHENTICATION_BACKENDS`` setting::

  AUTHENTICATION_BACKENDS = (
    'django.contrib.auth.backends.ModelBackend',
    'lazysignup.backends.LazySignupBackend',
  )
  
If you are using Django prior to 1.2, you should override the 
``lazysignup/convert.html``  template to remove the ``{% csrf_token %}`` 
template tag. This may be handled more elegantly in a future release.

Finally, you need to add lazysignup to your URLConf, using something like
this::

  urlpatterns += (''
      (r'^convert/', include('lazysignup.urls')),
  )


Usage
=====

The package works by creating temporary user accounts based on a user's 
session key whenever a flagged view is requested. You can specify which
views trigger this behaviour using the ``lazysignup.decorators.allow_lazy_user``
decorator.

When an anonymous user requests such a view, a temporary user account will be 
created for them, and they will be logged in. The user account will have
an unusable password set, so that it can't be used to log in as a regular
user. Hence, the way to tell a regular use from a temporary user is to call
the ``user.has_usable_password()`` method. If this returns ``False``, then the
user is temporary. Note that ``user.is_anonymous()`` will return ``False`` 
and ``user.is_authenticated()`` will return ``True``.

A view is provided to allow such users to convert their temporary account into
a real user account by providing a username and a password.

A Django management command is provided to clear out stale, uncoverted user
accounts - although this depends on your use of database-backed sessions, and
assumes that all user accounts with an expired session are safe to delete. This
may not be the case for all apps, so you may wish to provide your own cleaning
script. 

The ``allow_lazy_user`` decorator
---------------------------------

Use this decorator to indicate that accessing the view should cause anonymous
users to have temporary accounts created for them. 

For example::

  from django.http import HttpResponse
  from lazysignup.decorators import allow_lazy_user
{'fraction_non_alphanumeric': 0.08799206086668872, 'fraction_numerical': 0.0019847833278200462, 'mean_word_length': 4.337157987643424, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, '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': '4836158', 'n_tokens_mistral': 1683, 'n_tokens_neox': 1623, 'n_words': 806}