django-privateurl 1.4.0

Installation

Requirements:

• Django v1.8+

1. Install django-privateurl.

• Via pip:

  $ pip install django-privateurl

• Via setuptools:

  $ easy_install django-privateurl

For install development version use git+https://github.com/liminspace/django-privateurl.git@master instead django-privateurl.

2. Set up settings.py in your django project.

INSTALLED_APPS = (
  ...,
  'privateurl',
)

3. Add url pattern in urls.py:

urlpatterns = [
    ...
    url(r'^private/', include('privateurl.urls', namespace='privateurl')),
]

4. Run migrate:

$ manage.py migrate

Usage

First you need create PrivateUrl using create class method:

PrivateUrl.create(action, user=None, expire=None, data=None, hits_limit=1, auto_delete=False,
                  token_size=None, replace=False, dashed_piece_size=None)

• action – is a slug that using in url and allow distinguish one url of another

• user – is user instance that you can get in request process

• expire – is expiration date for private url. You can set datetime or timedelta

• data – is additional data that will be saved as JSON. Setting a dict object is good idea

• hits_limit – is limit of requests. Set 0 for unlimit

• auto_delete – set True if you want remove private url object when it will be not available

• token_size – set length of token. You can set number of size or tuple with min and max size. Keep None for using value from settings.PRIVATEURL_DEFAULT_TOKEN_SIZE

• replace – set True if you want remove old exists private url for user and action before creating one

• dashed_piece_size – split token with dash every N symbols. Keep None for using value from settings.PRIVATEURL_DEFAULT_TOKEN_DASHED_PIECE_SIZE

For example:

from privateurl.models import PrivateUrl

purl = PrivateUrl.create('registration-confirmation', user=user)
user.send_email(
    subject='Registration confirmation',
    body='Follow the link for confirm your registration: {url}'.format(
        url=purl.get_absolute_url(),
    ),
)

For catch private url request you have to create receiver for privateurl_ok signal:

from django.dispatch import receiver
from dju_privateurl.signals import privateurl_ok, privateurl_fail

@receiver(privateurl_ok)
def registration_confirm(request, obj, action, **kwargs):
    if action != 'registration-confirmation':
        return
    if obj.user:
        obj.user.registration_confirm(request=request)

if you want process invalid private url, you can create receiver for privateurl_fail signal:

from django.dispatch import receiver
from dju_privateurl.signals import privateurl_fail

@receiver(privateurl_fail)
def registration_confirm_fail(request, obj, action, **kwargs):
    if action != 'registration-confirmation':
        return
    if obj:
        # private url is expired or has exceeded ``hits_limit``
        pass
    else:
        # private url doesn't exists or token in url is not correct
        pass

After processing privateurl_ok signal will be redirected to root page /.

After processing privateurl_fail signal will be raised Http404 exception.

If you want change this logic you can return dict with key response in receiver:

from django.shortcuts import redirect, render
from django.dispatch import receiver
from dju_privateurl.signals import privateurl_ok, privateurl_fail

@receiver(privateurl_ok)
def registration_confirm(request, obj, action, **kwargs):
    if action != 'registration-confirmation':
        return
    if obj.user:
        obj.user.registration_confirm(request=request)
        obj.user.login()
        return {'response': redirect('user_profile')}

@receiver(privateurl_fail)
def registration_confirm_fail(request, obj, action, **kwargs):
    if action != 'registration-confirmation':
        return
    return {'response': render(request, 'error_pages/registration_confirm_fail.html', status=404)}

For getting data you need use method get_data():

@receiver(privateurl_ok)
def registration_confirm(request, obj, action, **kwargs):
    ...
    data = obj.get_data()
    ...

Settings

PRIVATEURL_URL_NAMESPACE – namespace that you setted in urls.py. By default it is privateurl.

PRIVATEURL_DEFAULT_TOKEN_SIZE – default size of token that will be generated using create or generate_token methods. By default it is (8, 64).

PRIVATEURL_DEFAULT_TOKEN_DASHED_PIECE_SIZE – default number of size of pieces that joined by dash that using in create or generate_token methods. By default it is 12.