django-lock-tokens 0.1.3

Table of Contents

1. Install

2. TL;DR

3. LockableModel proxy

4. LockableModelAdmin for admin interface

5. Session-based usage: lock_tokens.sessions module

6. Session-based usage: lock_tokens.decorators module

7. REST API

8. REST API Javascript client

9. Settings

10. Tests

Install

1. Run pip install django-lock-tokens

2. Add lock_tokens to your INSTALLED_APPS setting. As django-lock-tokens uses the contenttypes framework, make sure it is also available in your INSTALLED_APPS setting:

INSTALLED_APPS = [
    ...
    'django.contrib.contenttypes',
    ...
    'lock_tokens',
]

3. Run python manage.py migrate from the root of your django project to install the lock tokens model.

4. If you want to use the LockableAdmin and all the session-based functionalities, make sure you have enabled a session middleware in your settings, for example:

MIDDLEWARE_CLASSES = (
    ...
    'django.contrib.sessions.middleware.SessionMiddleware',
    ...
)

5. If you want to use the REST API, include lock_tokens.urls with the correct namespace in your urls.py like this (it is mandatory if you want to use the LockableModelAdmin):

urlpatterns = [
  ...
  url(r'^lock_tokens/', include('lock_tokens.urls', namespace='lock-tokens')),
  ...
]

TL;DR

After having completed previous steps, using the locking mechanism in your views is as simple as this:

from django.http import HttpResponseForbidden
from lock_tokens.exceptions import AlreadyLockedError, UnlockForbiddenError
from lock_tokens.sessions import check_for_session, lock_for_session, unlock_for_session

from my_app.models import MyModel

def view_with_object_edition(request):
  """This view locks the instance of MyModel that is to be edited."""
  # Get MyModel instance:
  obj = MyModel.objects.get(...)
  try:
      lock_for_session(obj, request.session)
  except AlreadyLockedError:
      return HttpResponseForbidden("This resource is locked, sorry !")
  # ... Do stuff
  return render(...)

def view_that_saves_object(request):
  """This view locks the instance of MyModel that is to be edited."""
  # Get MyModel instance:
  obj = MyModel.objects.get(...)
  if not check_for_session(obj, request.session):
      return HttpResponseForbidden("Cannot modify the object, you don't have the lock.")
  # ... Do stuff
  unlock_for_session(obj, request.session)
  return render(...)

Or use it directly in your Django templates to handle locking on the client side:

{% load lock_tokens_tags %}
{% lock_tokens_api_client %}
...
<script type="text/javascript">
  window.addEventListener('lock_tokens.clientready', function () {
    LockTokens.lock(...);
    ...
    LockTokens.unlock(...);
  });
</script>

LockableModel proxy

To make one of your models lockable, use the LockableModel class. LockableModel is just a Django proxy model, which simply provides additional locking methods to your models.

So you can either make your models inherit from LockableModel:

from lock_tokens.models import LockableModel

class MyModel(LockableModel):
    ...


obj = MyModel.get(...)
token = obj.lock()

or you can simply use it as a proxy on a given model instance:

from lock_tokens.models import LockableModel

from my_app.models import MyModel

obj = MyModel.get(...)
token = LockableModel.lock(obj)

This can be useful if you don’t want to expose the locking methods for your models everywhere, or if you want to lock resources that come from a third party application.

Note that as LockableModel is just a proxy model, make your models inherit from it won’t change their fields so there will be no additional migrations required.

Additionally, if your model inherits from LockableModel, the objects Manager has a specific method that allows you to get and lock a model like so:

>>>obj, token = MyModel.get_and_lock(...<usual get arguments>)

If you already overrided the default objects manager with a custom one and that you want to get this method available, make your custom manager inherit from lock_tokens.managers.LockableModelManager.

def test(myObject):
    try:
        token = myObject.lock()
    except AlreadyLockedError:
        print "This object is already locked"
    return token

>>>token = test(obj)
{"token": "9692ac52a27a40308b82b49b77357c97", "expires": "2016-06-23 09:48:06"}
>>>test(obj)
"This object is already locked"
>>>test(obj, token['token'])
{"token": "9692ac52a27a40308b82b49b77357c97", "expires": "2016-06-23 09:48:26"}

LockableModelAdmin for admin interface

If you want to make the admin interface lock-aware, and lock objects that are edited, simply make your ModelAdmin class inherit from LockableModelAdmin:

from lock_tokens.admin import LockableModelAdmin
from django.contrib import admin

from my_app.models import MyModel

class MyModelAdmin(LockableModelAdmin):
  ...

admin.site.register(MyModel, MyModelAdmin)

With this, when accessing a given instance of MyModel from the admin interface, it will check that the instance is not locked. If it is not, it will lock it. If it is, then there will be a warning message displayed to inform that the object cannot be edited, and the saving buttons will not appear. And if despite this, the change form is sent, it will raise a PermissionDenied exception so you will get a HTTP 403 error.

Session-based usage: lock_tokens.sessions module

In most cases, it will be the easiest way to deal with lock tokens, as you won’t need to handle them at all.

Session-based usage: lock_tokens.decorators module

This module provides view decorators for common use cases.

from lock_tokens.decorators import locks_object

@locks_object(MyModel, lambda request: request.GET.get('my_model_id'))
def myview(request):
  # In this example the view will lock the MyModel instance with the id
  # provided in the request GET parameter my_model_id
  ...

@locks_object(MyModel, lambda request, object_id: object_id)
def anotherview(request, object_id):
  # In this example the view will lock the MyModel instance with the id
  # provided as the second view argument
  ...

REST API

If you want to use locking mechanism from outside your views, there is a simple HTTP API to handle tokens. It does not use sessions at all, so you need to handle the tokens yourself in this case.

Here are the different entry points, where <app_label> is the name of the application of the concerned model, <model> is the name of the model, <object_id> is the id of the cmodel instance, and <token> is the lock token value.

REST API Javascript client

The application includes a javascript client to interact with the API. To enable it, simply add the following lines to your template, somewhere in the <body> section

{% load lock_tokens_tags %}
{% lock_tokens_api_client %}

Don’t forget to include the REST API urls with the correct namespace as described in section 1, otherwise it won’t work.

Adding those lines in your template will create a variable named LockTokens, and emit a lock_tokens.clientready event when it is available in the javascript scope. This object has the following methods (parameters are self-describing):

Settings

You can override lock_token default settings by adding a dict named LOCK_TOKENS to your settings.py like so:

LOCK_TOKENS = {
  'API_CSRF_EXEMPT': True,
  'DATEFORMAT': "%Y%m%d%H%M%S",
  'TIMEOUT': 60,
}

Tests

To run tests, make sure Django >= 1.7 is installed in your virtualenv, then simply run python ./runtests.py from the root of the repository.