Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

OpenWISP 2 Utilities

Project description Requirements Status

Python and Django utilities shared between different OpenWISP modules.

Current features

  • Customized admin theme for OpenWISP modules
  • Multitenant admin interface and testing mixins
  • TimeStamped models and mixins which add self-updating created and modified fields.
  • DependencyLoader: template loader which looks in the templates dir of all django-apps listed in EXTENDED_APPS
  • DependencyFinder: finds static files of django-apps listed in EXTENDED_APPS

Project goals

  • Minimize code duplication among OpenWISP modules

Install stable version from pypi

Install from pypi:

pip install openwisp-utils
# install optional dependencies for openwisp-users too
pip install openwisp-utils[users]

Install development version

Install tarball:

pip install

Alternatively you can install via pip using git:

pip install -e git+git://

If you want to contribute, install your cloned fork:

git clone<your_fork>/openwisp-utils.git
cd openwisp-utils
python develop

Using the utilities in OpenWISP modules

INSTALLED_APPS in should look like the following if you want to use all the utilities

    # customized admin theme
    # all-auth
    # openwisp2 modules
    # admin

Using the admin_theme

For using the customized admin theme,

  • Make sure you’ve added openwisp_utils.admin_theme to INSTALLED_APPS in
  • Add the following into your file which contains admin urls.
from django.conf.urls import include, url

from openwisp_utils.admin_theme.admin import admin, openwisp_admin


urlpatterns = [
    # other url patterns
    url(r'^admin/', include(,

Admin mixins

These are mixins which make a ModelAdmin class multitenant: users will see only the objects related to the organizations they are associated with.

  • MultitenantAdminMixin: adding this mixin to a ModelAdmin class will make it multitenant. Set multitenant_shared_relations to the list of parameters you wish to have only organization specific options.
  • MultitenantOrgFilter: admin filter that shows only organizations the current user is associated with in its available choices.
  • MultitenantRelatedOrgFilter: similar MultitenantOrgFilter but shows only objects which have a relation with one of the organizations the current user is associated with.
  • TimeReadonlyAdminMixin: Admin mixin which adds two readonly fields created and modified. This is an admin mixin for models inheriting TimeStampedEditableModel which adds the fields created and modified to the database.

Example usage:

from django.contrib import admin

from openwisp_utils.admin import (MultitenantAdminMixin,

from .models import Book, Shelf

class BaseAdmin(MultitenantAdminMixin, TimeReadonlyAdminMixin, admin.ModelAdmin):

class ShelfAdmin(BaseAdmin):
    list_display = ['name', 'organization']
    list_filter = [('organization', MultitenantOrgFilter)]
    fields = ['name', 'organization', 'created', 'modified']

class BookAdmin(BaseAdmin):
    list_display = ['name', 'author', 'organization', 'shelf']
    list_filter = [('organization', MultitenantOrgFilter),
                   ('shelf', MultitenantObjectFilter)]
    fields = ['name', 'author', 'organization', 'shelf', 'created', 'modified']
    multitenant_shared_relations = ['shelf']

Using DependencyLoader and DependencyFinder

Add the list of all packages extended to EXTENDED_APPS in If you’ve extended django_netjsonconfig and django_x509:

EXTENDED_APPS = ['django_netjsonconfig', 'django_x509']


Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS in



Add openwisp_utils.staticfiles.DependencyFinder to TEMPLATES_LOADERS in or as shown below.

        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'OPTIONS': {
            'loaders': [
            'context_processors': [

Quality Assurance checks

This package contains some common QA checks that are used the automated builds of different OpenWISP modules.


Ensures the latest migrations created have a human readable name.

We want to avoid having many migrations named like

This way we can reconstruct the evolution of our database schemas faster, with less efforts and hence less costs.

Usage example:

checkmigrations --migration-path ./django_freeradius/migrations/


Ensures the last commit message follows our commit message style guidelines.

We want to keep the commit log readable, consistent and easy to scan in order to make it easy to analyze the history of our modules, which is also a very important activity when performing maintenance.

Usage example:

checkcommit --message "$(git log --format=%B -n 1)"

Installing for development

Install sqlite:

sudo apt-get install sqlite3 libsqlite3-dev

Install your forked repo:

git clone git://<your_fork>/openwisp-utils
cd openwisp-utils/
python develop

Install test requirements:

pip install -r requirements-test.txt

Create database:

cd tests/
./ migrate
./ createsuperuser

Set EMAIL_PORT in to a port number (eg: 1025):

EMAIL_PORT = '1025'

Launch development server and SMTP deubgging server:

./ runserver
# open another session and run
python -m smtpd -n -c DebuggingServer localhost:1025

You can access the admin interface of the test project at

Run tests with:



  1. Announce your intentions in the OpenWISP Mailing List and open relavant issues using the issue tracker
  2. Fork this repo and install the project following the instructions
  3. Follow PEP8, Style Guide for Python Code
  4. Write code and corresponding tests
  5. Ensure that all tests pass and the test coverage does not decrease
  6. Document your changes
  7. Send a pull request





Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
openwisp_utils-0.2.2-py2.py3-none-any.whl (61.4 kB) Copy SHA256 hash SHA256 Wheel py2.py3
openwisp-utils-0.2.2.tar.gz (58.4 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page