Package: django-lock-tokens
django-lock-tokens is a Django application that provides a locking mechanism to prevent concurrency editing.It is not user-based nor session-based, it is just token based. When you lock a resource, you are given a token string with an expiration date, and you will need to provide this token to unlock that resource.The application provides some useful functions to handle this token mechanism with sessions if you want to, and a REST API (with a javascript client for it) to deal with lock tokens without sessions.Here is a non exhaustive list of the features coming with this token-based approach, to help you choosedjango-lock-tokens(or not!) over other concurrent edition preventing solutions:No need to modify your models to use the locking mechanism : you don’t “pollute” your datamodel with “non-data” fields. This also means you can use the locking mechanism on third party models that cannot be modifiedNo need to use sessions (but you can still use it if you want to)Ability to check if an object is locked BEFORE trying to modify itRest API (+ javascript client to use it) out-of-the-boxAdmin interface integrationTable of ContentsRequirementsInstallTL;DRHow it worksLockableModel proxyLockableModelAdmin for admin interfaceSession-based usage: lock_tokens.sessions moduleSession-based usage: lock_tokens.decorators moduleREST APIREST API Javascript clientSettingsTestsRequirementsPython (2.7, 3.3, 3.4, 3.5)Django (1.8, 1.9, 1.10, 1.11, 2.0, 2.1)InstallRunpip installdjango-lock-tokensAddlock_tokensto yourINSTALLED_APPSsetting. As django-lock-tokens uses thecontenttypesframework, make sure it is also available in yourINSTALLED_APPSsetting:INSTALLED_APPS=[...'django.contrib.contenttypes',...'lock_tokens.apps.LockTokensConfig',]Runpython manage.py migratefrom the root of your django project to install the lock tokens model.If you want to use theLockableAdminand 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',...)If you want to use the REST API, includelock_tokens.urlswith the correct namespace in yoururls.pylike this (it is mandatory if you want to use theLockableModelAdmin):urlpatterns=[...url(r'^lock_tokens/',include('lock_tokens.urls',namespace='lock-tokens')),...]TL;DRAfter having completed previous steps, using the locking mechanism in your views is as simple as this:fromdjango.httpimportHttpResponseForbiddenfromlock_tokens.exceptionsimportAlreadyLockedError,UnlockForbiddenErrorfromlock_tokens.sessionsimportcheck_for_session,lock_for_session,unlock_for_sessionfrommy_app.modelsimportMyModeldefview_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)exceptAlreadyLockedError:returnHttpResponseForbidden("This resource is locked, sorry !")# ... Do stuffreturnrender(...)defview_that_saves_object(request):"""This view locks the instance of MyModel that is to be edited."""# Get MyModel instance:obj=MyModel.objects.get(...)ifnotcheck_for_session(obj,request.session):returnHttpResponseForbidden("Cannot modify the object, you don't have the lock.")# ... Do stuffunlock_for_session(obj,request.session)returnrender(...)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>How it worksTo avoid concurrency editing,django-lock-tokensprovides some interfaces to lock and check lock on any model instance before changing it (including third party model instances).
This is handled via an internal model (LockToken). There can be only oneLockTokeninstance per model instance.The lock token lifecycle is the following:When a lock is created for an object by an entity, it is valid for a certain amount of time. The entity is given alock token key(a string) that it must hold to perform actions with valid lock required. A newLockTokeninstance is created in database, after having deleted a potential expired instance in database.If the entity that holds the lock token key no longer needs the lock on the object, it can unlock this object by providing the lock token key. TheLockTokeninstance is then removed from database.The entity that holds the lock token key can also renew the lock token by providing the lock token key.If the lock token is not renewed until the expiration time, it becomes expired, but stays in database until a new lock is created on this instance (or the entity that holds the lock token key deletes it).So to use this mechanism correctly, you shouldrequirea valid lock token key and renew the lock in any method where an object is saved and you want to prevent concurrency editing. Based on the 4 previous points, we can see that there can be 3 cases for a lock token key:The lock token key has a corresponding lock token in database, and it has not expired.The lock token key has a corresponding lock token in database, but it has expired.The lock token key has no correponding lock token in database for the object.For case 1, it is ok to save the object and then unlock the object by deleting the lock token. The token key is stillVALID.For case 2, the lock has expired but no other entity has created a lock on the object in the meantime. So it is still ok to save the object as it will not overwrite any changes. The token key is stillVALID.In case 3, it means that the lock token created by the entity has expired, and that another entity has taken a lock on the object in the meantime and could have done some changes on it. So it is not ok to save changes. The token key isINVALID.Here is an example to understand the case 3:Alice takes a lock on an object and opens up its editing interface.A ``LockToken`` instance ``lt1`` is created in database, and Alice is given a lock token keyAlice walks away from her computer, the lock expires.``lt1`` is still in databaseBob takes a lock on the same object.``lt1`` is deleted from database, and a new ``LockToken`` instance ``lt2`` is createdBob edits the object in the interface, clicks save. The object is modified and the lock is released.``lt2`` is deleted. The object has no longer any lock in databaseAlice returns, clicks save. The lock token key she holds has become invalid, so she gets an error.This example shows how it is important to require aVALIDlock token key to prevent concurrency editing.LockableModelproxyTo make one of your models lockable, use theLockableModelclass.LockableModelis just a Django proxy model, which simply provides additional locking methods to your models.So you can either make your models inherit fromLockableModel:fromlock_tokens.modelsimportLockableModelclassMyModel(LockableModel):...obj=MyModel.get(...)token=obj.lock()or you can simply use it as a proxy on a given model instance:fromlock_tokens.modelsimportLockableModelfrommy_app.modelsimportMyModelobj=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 asLockableModelis 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 fromLockableModel, theobjectsManager has a specific method that allows you to get and lock a model like so:>>>obj,token=MyModel.get_and_lock(...<usualgetarguments>)If you already overrided the defaultobjectsmanager with a custom one and that you want to get this method available, make your custom manager inherit fromlock_tokens.managers.LockableModelManager.LockableModel.lock(self, token=None)Locks the given object, or renew existing lock if the token parameter is provided.Returns adictcontaining a token a its expiration date.Raises alock_tokens.exceptions.AlreadyLockedErrorif the resource is already locked, and alock_tokens.exceptions.InvalidTokenif the specified token is invalid.Example:deftest(myObject):try:token=myObject.lock()exceptAlreadyLockedError:print"This object is already locked"returntoken>>>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"}LockableModel.unlock(self, token)Unlocks the given object if the provided token is correct.Raises alock_tokens.exceptions.UnlockForbiddenErrorLockableModel.is_locked(self)Returns a boolean that indicates whether the given object is currently locked or not.LockableModel.check_lock(self, token)Returns a boolean that indicates if the given token is valid for this object. Will also returnTruewith a warning if the object is not locked (lock expired or no lock).LockableModelAdminfor admin interfaceIf you want to make the admin interface lock-aware, and lock objects that are edited,
simply make yourModelAdminclass inherit fromLockableModelAdmin:fromlock_tokens.adminimportLockableModelAdminfromdjango.contribimportadminfrommy_app.modelsimportMyModelclassMyModelAdmin(LockableModelAdmin):...admin.site.register(MyModel,MyModelAdmin)With this, when accessing a given instance ofMyModelfrom 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 aPermissionDeniedexception so you will get a HTTP 403 error.Overrindingchange_form_templateinLockableModelAdminIf you want to override thechange_form_template, but still make sure the lock will be released when leaving the page without saving, don’t forget to add theadmin_lock_handlertemplate tag. This template tag needs 4 arguments: the application name of the object, the model name of the object, the object id and the lock token key. So don’t forget to add those (especially the lock token) into your template context if you also override thechange_viewmethod.Example to add the template tag to your custom template if you don’t overridechange_view:...
{% load lock_tokens_tags %}
...
{% if lock_token %}
  {% admin_lock_handler opts.app_label opts.model_name original.id lock_token %}
{% endif %}Session-based usage:lock_tokens.sessionsmoduleIn most cases, it will be the easiest way to deal with lock tokens, as you won’t need to handle them at all.lock_for_session(obj, session, force_new=False)Lock an object in the given session. This function will try to lock the object,
and if it succeeds, it will hold the token value in a session variable.There is aforce_newoptional parameter that you can set toTrueif you want to force a new lock generation without using a potentially existing token key stored in session. This is to be used with caution (i.e. exclusively in methods that only read the object, not in methods that save it) as it could lead to a potential overwriting if the session holds an invalid token.
To sum up: do not set this parameter toTrueunless you are sure of what you are doing!Raises alock_tokens.exceptions.AlreadyLockedErrorif the resource is already locked, and alock_tokens.exceptions.InvalidTokenerror if the session holds an invalid token.unlock_for_session(obj, session)Unlocks an object in the given session.Raises alock_tokens.exceptions.UnlockForbiddenErrorif the session does not hold the lock on the object.check_for_session(obj, session)Check if an object has a valid lock in the given session.ReturnsTrueif the session holds a valid lock (even if it has expired), andFalseif the session holds an invalid lock or no lock.Session-based usage:lock_tokens.decoratorsmoduleThis module provides view decorators for common use cases.locks_object(model, get_object_id_callable)Locks an object before executing view, and keep lock token in the request session. Does not unlock it when the view returns.Arguments:model: the concerned django Modelget_object_id_callable: a callable that will return the concerned object id based on the view argumentsExample:fromlock_tokens.decoratorsimportlocks_object@locks_object(MyModel,lambdarequest:request.GET.get('my_model_id'))defmyview(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,lambdarequest,object_id:object_id)defanotherview(request,object_id):# In this example the view will lock the MyModel instance with the id# provided as the second view argument...holds_lock_on_object(model, get_object_id_callable)Locks an object before executing view, and keep lock token in the request session. Hold lock until the view is finished executing, then release it.Arguments:model: the concerned django Modelget_object_id_callable: a callable that will return the concerned object id based on the view argumentsSee examples forlocks_object.REST APIIf 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.POST/lock_tokens/<app_label>/<model>/<object_id>/Locks object. Returns a JSON response with “token” and “expires” keys.Returns a 404 HTTP error if the object could not be found.Returns a 403 HTTP error if the object is already locked.GET/lock_tokens/<app_label>/<model>/<object_id>/<token>/Returns a JSON response with “token” and “expires” keys.Returns a 404 HTTP error if the object could not be found.Returns a 403 HTTP error if the token is incorrect.PATCH/lock_tokens/<app_label>/<model>/<object_id>/<token>/Renews the lock on the object. Returns a JSON response with “token” and “expires” keys.Returns a 404 HTTP error if the object could not be found.Returns a 403 HTTP error if the token is incorrect.DELETE/lock_tokens/<app_label>/<model>/<object_id>/<token>/Unlocks object.Returns a 404 HTTP error if the object could not be found.Returns a 403 HTTP error if the token is incorrect.REST API Javascript clientThe 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 namedLockTokens, and emit alock_tokens.clientreadyevent when it is available in the javascript scope. This object has the following methods (parameters are self-describing):LockTokens.lock(app_label, model, object_id, callback)Locks the corresponding object. When the call to the API is completed, calls thecallbackmethod with alock_tokens.Tokeninstance as an argument, ornullif the API request failed.NB: TheLockTokenshandles the tokens for you, so you don’t need to read API responses and/or store tokens yourself.LockTokens.register_existing_lock_token(app_label, model, object_id, token_string, callback)Add an existing token to theLockTokensregistry. This method is useful for example when you want to handle on client side a lock that has been set on the server side. You must provide the token string in addition to other parameters, the client will make a call to the API to ensure the token is valid and get its expiration date. Calls thecallbackmethod with alock_tokens.Tokeninstance as an argument, ornullif the registration failed.LockTokens.unlock(app_label, model, object_id, callback)Locks the corresponding object. When the call to the API is completed, calls thecallbackmethod with a boolean that indicates whether the API request has succeeded. Note that this method can be called only on an object that has been locked or registered as locked by theLockTokensobject.LockTokens.hold_lock(app_label, model, object_id)Holds a lock on the corresponding object. It is like thelockmethod, except it renews the token each time it is about to expire. A call tounlockwill stop the lock holding.LockTokens.clear_all_locks(callback)Unlocks all registered objects. Callscallbackwith no arguments when unlocking of every objects is done.SettingsYou can overridelock_tokendefault settings by adding adictnamedLOCK_TOKENSto yoursettings.pylike so:LOCK_TOKENS={'API_CSRF_EXEMPT':True,'DATEFORMAT':"%Y%m%d%H%M%S",'TIMEOUT':60,}TIMEOUTThe validity duration for a lock token in seconds. Defaults to3600(one hour).DATEFORMATThe format of the expiration date returned in the tokendict. Defaults to"%Y-%m-%d%H:%M:%S%Z"API_CSRF_EXEMPTA boolean that indicates whether to deactivate CSRF checks on the API views or not. Defaults toFalse.TestsTo run tests simply run from the root of the repository:source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install tox
(myenv) $ toxCreditsTools used in rendering this package:Cookiecuttercookiecutter-djangopackageHistory0.2.5 (2019-02-07)Fix issue #10_0.2.4 (2018-11_30)The HTTP API endpoint to get token information now returns the token information even when it has expired, because it is still valid to use (seethis)0.2.3 (2018-10-31)FixesLockableModelfor Python 2.70.2.2 (2018-10-31)FixesLockableModelto allow to use it as a proxy0.2.1 (2018-10-04)FixesLockToken.savemethod to prevent potential transaction errorsAdds a template tag to handle lock on the client side when overriding defaultchange_form_templateinLockableModelAdminBetter handling of invalid lock token strings (see discussionhere) to prevent overwriting0.1.4 (2017-09-07)Adds acreatedfield to theLockTokenmodel