Privex Django Lock Manager (django-lockmgr) documentation

Privex Logo

Welcome to the documentation for Privex’s Django Lock Manager - a small, open source Python 3 package for Django, designed to provide simple, frustration free locks in your Django application, without requiring any additional services like Redis / Memcached.

This documentation is automatically kept up to date by ReadTheDocs, as it is automatically re-built each time a new commit is pushed to the Github Project

Quick install

Installing with Pipenv (recommended)

pipenv install django-lockmgr

Installing with standard pip3

pip3 install django-lockmgr

Add lockmgr to your INSTALLED_APPS

INSTALLED_APPS = [
    'django.contrib.admin.apps.SimpleAdminConfig',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ...
    'lockmgr'
]

Run the migrations

./manage.py migrate lockmgr

All Documentation

Installing Django Lock Manager

(Alternative) Manual install from Git

You may wish to use the alternative installation methods if:

  • You need a feature / fix from the Git repo which hasn’t yet released as a versioned PyPi package

  • You need to install django-lockmgr on a system which has no network connection

  • You don’t trust / can’t access PyPi

  • For some reason you can’t use pip or pipenv

Option 1 - Use pip to install straight from Github

pip3 install git+https://github.com/Privex/django-lockmgr

Option 2 - Clone and install manually

# Clone the repository from Github
git clone https://github.com/Privex/django-lockmgr
cd django-lockmgr

# RECOMMENDED MANUAL INSTALL METHOD
# Use pip to install the source code
pip3 install .

# ALTERNATIVE MANUAL INSTALL METHOD
# If you don't have pip, or have issues with installing using it, then you can use setuptools instead.
python3 setup.py install

Post-installation

Django Lock Manager requires very little configuration after installation. Simply add it to your INSTALLED_APPS, and run ./manage.py migrate lockmgr to create the database tables.

Add lockmgr to your INSTALLED_APPS

INSTALLED_APPS = [
    'django.contrib.admin.apps.SimpleAdminConfig',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ...
    'lockmgr'
]

Run the migrations

./manage.py migrate lockmgr

lockmgr.lockmgr

This is the main module file for `Django Lock Manager`_ (django-lockmgr) and contains lock management functions/classes.

lockmgr.models

lockmgr.management.commands

How to use the unit tests

This module contains test cases for Privex’s Django Lock Manager (django-lockmgr).

Testing pre-requisites

  • Install all core and development requirements listed in requirements.txt

  • Either PostgreSQL or MySQL is recommended, however the default SQLite3 may or may not work.

  • Python 3.7 or 3.8 is recommended at the time of writing this. See README.md in-case this has changed.

pip3 install -r requirements.txt

If you’re using MySQL / Postgres, create a .env file in the root of the project, and enter the database connection details:

# If not specified, DB_USER and DB_NAME both default to 'lockmgr'
DB_USER=root
DB_NAME=lockmgr
# If not specified, then the DB user password defaults to blank
DB_PASS=
# If not specified, the DB host defaults to localhost, and the port as blank (automatic depending on backend)
DB_HOST=localhost
DB_PORT=5432
# If not specified, the DB backend defaults to SQLite3 (stored in db.sqlite3 in root of project)
# If you're using PostgreSQL:
DB_BACKEND=postgresql
# If you're using MySQL / MariaDB:
DB_BACKEND=mysql

Running the tests via Django Test Runner / Django-Nose

After installing the packages listed in requirements.txt, you should now be able to run the tests using Django’s manage.py:

# Ensure you have all development requirements installed
user@host: ~/django-lockmgr $ pip3 install -r requirements.txt

# Then run the tests using manage.py
user@host: ~/django-lockmgr $ ./manage.py test

nosetests --verbosity=1
Creating test database for alias 'default'...
............................
----------------------------------------------------------------------
Ran 28 tests in 20.291s

OK
Destroying test database for alias 'default'...

For more verbosity, simply add --verbose to the end of the command:

$ ./manage.py test --verbose

    nosetests --verbose --verbosity=2
    
    Creating test database for alias 'default' ('test_lockmgr')...
    Operations to perform:
      Synchronize unmigrated apps: django_nose
      Apply all migrations: lockmgr
    Synchronizing apps without migrations:
      Creating tables...
        Running deferred SQL...
    Running migrations:
      Applying lockmgr.0001_initial... OK
      
    Locking test_getlock then checking if Lock is raised when calling it again. ... ok
    Locking test_unlock, unlocking it, then lock/unlock again to confirm it was freed. ... ok
    Test that expired locks are correctly removed ... ok
    Test that LockMgr runs code with 'wait for lock expiry' when lock expires within wait period ... ok
    Test that LockMgr raises Locked with 'wait for lock expiry' when lock still locked after waiting period ... ok
    Locking test_lockmgr and test_lockmgr2 using LockMgr, then verifying the lock was created ... ok
    Testing that LockMgr correctly removes Locks after an exception ... ok
    Renew an existing lock by lock name and confirm locked_until was increased ... ok
    Renew an existing lock by lock name with add_time=True and confirm locked_until was increased ... ok
    Renew an existing lock by Lock object with add_time=True and confirm locked_until was increased ... ok
    Renew an existing lock by Lock object and confirm locked_until was increased ... ok
    Renew a non-existent lock by lock name and confirm LockNotFound is raised ... ok
    Renew a non-existent lock by lock name with create=True and confirm new lock is created ... ok
    
    ----------------------------------------------------------------------
    Ran 13 tests in 10.106s
    
    OK
    Destroying test database for alias 'default' ('test_lockmgr')...

Copyright:

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        Django Database Lock Manager               |
|        License: X11/MIT                           |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

Unit Test List / Overview

test_lockmgr

test_lockmgr_class

test_renew