Metadata-Version: 1.0
Name: django-lazysignup
Version: 0.4.0
Summary: Lazy signup for Django
Home-page: http://github.com/danfairs/django-lazysignup
Author: Dan Fairs
Author-email: dan@fezconsulting.com
License: BSD
Description: 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 alpha software. Bug reports, patches and extensions
        are welcomed. While this package is in alpha, changes may be made in second-dot
        point releases without regards to backwards compatibility. This will change when
        the software stabilises.
        
        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',
        )
        
        You'll also need the middleware installed. It should come between the session
        and auth backends::
        
        MIDDLEWARE_CLASSES = (
        "django.middleware.common.CommonMiddleware",
        "django.contrib.sessions.middleware.SessionMiddleware",
        "django.middleware.csrf.CsrfViewMiddleware",
        "lazysignup.middleware.LazySignupMiddleware",
        "django.contrib.auth.middleware.AuthenticationMiddleware",
        "django.contrib.messages.middleware.MessageMiddleware",
        "django.middleware.doc.XViewMiddleware",
        )
        
        
        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
        
        @allow_lazy_user
        def my_view(request):
        return HttpResponse(request.user.username)
        
        When accessing the above view, a very simple response containing the generated
        username will be displayed.
        
        Currently, the ``allow_lazy_user`` decorator needs to be the last decorator
        applied to a view function - in other words, it needs to appear first in the
        decorator list. For example, this works::
        
        @allow_lazy_user
        @csrf_protect
        @require_POST
        def make(request):
        pass
        
        This will not work::
        
        @csrf_protect
        @require_POST
        @allow_lazy_user
        def make(request):
        pass
        
        This is something that will be improved in a future version. Thanks to
        Jauco Noordzij for pointing this out.
        
        User agent blacklisting
        -----------------------
        
        The middleware will not created users for certain requests from blacklisted
        user agents. This is simply a fairly crude method for preventing many spurious
        users being created by passing search engines.
        
        The blacklist is specified with the ``USER_AGENT_BLACKLIST`` setting. This
        should be an iterable of regular expression strings. If the user agent string
        of a request matches a regex (``search()`` is used, so the match can be anywhere
        in the string) then a user will not be created.
        
        If the list is not specified, then the default is as follows
        
        - slurp
        - googlebot
        - yandex
        - msnbot
        - baiduspider
        
        Specifying your own ``USER_AGENT_BLACKLIST`` will replace this list.
        
        Using the convert view
        ----------------------
        
        Users will be able to visit the ``/convert/`` view. This provides a form with
        a username, password and password confirmation. As long as they fill in valid
        details, their temporary user account will be converted into a real user
        account that they can log in with as usual.
        
        You may pass your own form class into the `convert` view in order to customise
        user creation. The code requires expects the following:
        
        - It expects to be able to create the form passing in the generated ``User``
        object with an ``instance`` kwarg (in general, this is fine when using a
        ModelForm based on the User model)
        - It expects to be able to call ``save()`` on the form to convert the user
        to a real user
        - It expects to be able to call a ``get_credentials()`` method on the form
        to obtain a set of credentials to authenticate the new user with. The
        result of this call should be a dictionary suitable for passing to
        ``django.contrib.auth.authenticate()``. Typically, this would be a dict
        with ``username`` and ``password`` keys - but this may vary if you're using
        a different authentication backend.
        
        The default configuration, using the provided ``UserCreationForm``, should
        be enough for most users, but the customisation point is there if you need
        it.
        
        Maintenance
        -----------
        
        Over time, a number of user accounts that haven't been converted will build up.
        To avoid performance problems from an excessive number of user accounts, it's
        recommended that the ``remove_expired_users`` management command is run on
        a regular basis. It runs from the command line::
        
        python manage.py remove_expired_users
        
        In a production environment, this should be run from cron or similar.
        
        This works be removing user accounts from the system whose associated sessions
        are no longer in the session table. ``user.delete()`` is called for each user,
        so related data will be removed as well.
        
        Note of course that these deletes will cascade, so if you need to keep data
        associated with such users, you'll need to write your own cleanup job. It also
        expects that you're using database backed sessions. If that's not the case, then
        you'll again need to write your own cleanup.
        
        To Do
        -----
        
        There are a number of things on the to-do list:
        
        - Remove the restriction on  the ``allow_lazy_user`` decorator being first in
        the decorator list.
        
        Helping Out
        -----------
        
        If you want to add a feature or fix a bug, please go ahead! Fork the project
        on GitHub, and when you're done with your changes, let me know. Fixes and
        features with tests have a greater chance of being merged. To run the tests,
        do::
        
        python manage.py test --settings=lazysignup.test_settings lazysignup
        
        
        Note that the tests require the ``mock`` package.
        
        Changelog
        =========
        
        0.4.0
        -----
        
        This version fixes a number of issues, adds new features and has backwards-
        incompatible changes:
        
        - Fix a RST issue in README
        - Fix an issue where a POST to the convert view would break if the user was anonymous.
        The convert view now redirects to the LOGIN_URL by default, parameterised in the view.
        
        New features:
        
        - It is now easier to customise the process of converting a lazy user into a real user.
        Previous versions allowed a custom form to be passed to the ``convert`` view, but the
        code always expected a ``username`` and ``password1`` field to get credentials from to
        log the user in. Now, a new ``get_credentials()`` method is called on the form to obtain
        these credentials.
        - The tests module now includes a ``no_lazysignup`` decorator that you can apply to a
        method on your test case, which removes the lazy signup middleware for the duration
        of that test only. This is useful for testing what happens when a view that is
        marked with with the ``allow_lazy_user`` decorator ends up with an anonymous user
        (most commonly, when a search engine visits).
        
        Backwards-incompatible changes:
        
        - Generated usernames are now based on the session key, rather than actually being the
        session key. This is to avoid a potential security issue where an app might simply
        display a username, giving away a significant part of the user's session key. The
        username is now generated from a SHA1 hash of the session key. This change means that
        existing generated users will become invalid.
        
        0.3.0
        -----
        
        This version introduces a backwards-incompatible changes, renaming the ``@allow_lazy``
        decorator to ``@allow_lazy_user``. This is to avoid confusion with the decorator of
        the same name in ``django.utils.functional``.
        
        0.2.0
        -----
        
        This version fixes a number of issues:
        
        - Correct a duplicated test
        - Fix a bug where a new user would not be created if they already had a
        session key.
        
        It also introduces a new feature, user agent blacklisting. This aims to
        prevent explosive growth in the number of users created by search engines,
        etc. This feature is still in test, so patches and feedback welcome. Note that
        this introduces a backwards-incompatibly behaviour. Prior to this release,
        it was safe to assume that all views marked with the ``@allow_lazy`` decorator
        would receive an authenticated user. This is now no longer the case.
        
        See the README.rst file for more information.
        
        0.1.2
        -----
        
        * Compatibility fixes for Django <1.2
        * The convert view is now itself lazy
        
        0.1.1
        -----
        
        * Fix some packaging errors
        
        0.1
        ---
        
        * Initial release
        
        
Keywords: django lazy signup app user
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: Django
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
