Python and Django utilities shared between different OpenWISP modules.

The admin theme requires Django >= 2.2.

• Customized admin theme for OpenWISP modules
• Configurable navigation menu
• TimeStamped models and mixins which add self-updating created and modified fields.
• UUIDModel: base model with a UUID4 primary key
• KeyField: base field for a unique string key
• UUIDAdmin: base admin which defines a uuid field from a UUID primary key
• ReceiveUrlAdmin: base admin which defines a receive_url field
• get_random_key: generates an object key of 32 characters
• 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
• Test utilities: it contains utilities used for automated testing across various modules
• QA: logic and utilities to perform quality assurance checks across different modules

• Minimize code duplication among OpenWISP modules

Install from pypi:

pip install openwisp-utils
# install optional dependencies for tests (flake8, black and isort)
pip install openwisp-utils[qa]

Install tarball:

pip install https://github.com/openwisp/openwisp-utils/tarball/master

Alternatively you can install via pip using git:

pip install -e git+git://github.com/openwisp/openwisp-utils#egg=openwisp-utils

If you want to contribute, install your cloned fork:

git clone git@github.com:<your_fork>/openwisp-utils.git
cd openwisp-utils
python setup.py develop

INSTALLED_APPS in settings.py should look like the following if you want to use the OpenWISP admin-theme:

INSTALLED_APPS = [
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # customized admin theme
    'openwisp_utils.admin_theme',
    'django.contrib.sites',
    # admin
    'django.contrib.admin',
]

• Add openwisp_utils.admin_theme to INSTALLED_APPS in settings.py.

Add the list of all packages extended to EXTENDED_APPS in settings.py. If you've extended django_netjsonconfig and django_x509:

EXTENDED_APPS = ['django_netjsonconfig', 'django_x509']

Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS in settings.py.

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

Add openwisp_utils.loaders.DependencyLoader to template loaders in settings.py as shown below.

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'OPTIONS': {
            'loaders': [
                # ... other loaders ...
                'openwisp_utils.loaders.DependencyLoader',
            ],
            'context_processors': [
                # ... omitted ...
            ],
        },
    },
]

Add openwisp_utils.admin_theme.context_processor.menu_items to template context_processors in settings.py as shown below.

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'OPTIONS': {
            'loaders': [
                # ... omitted ...
            ],
            'context_processors': [
                # ... other context processors ...
                'openwisp_utils.admin_theme.context_processor.menu_items'
            ],
        },
    },
]

Add openwisp_utils.admin_theme.context_processor.admin_theme_settings to template context_processors in settings.py as shown below. This will allow to set OPENWISP_ADMIN_THEME_LINKS and OPENWISP_ADMIN_THEME_JS settings to provide CSS and JS files to customise admin theme.

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'OPTIONS': {
            'loaders': [
                # ... omitted ...
            ],
            'context_processors': [
                # ... other context processors ...
                'openwisp_utils.admin_theme.context_processor.admin_theme_settings'
            ],
        },
    },
]

default: openwisp_utils.admin_theme.admin.OpenwispAdminSite

If you need to use a customized admin site class, you can use this setting.

default: OpenWISP Admin

Title value used in the <title> HTML tag of the admin site.

default: OpenWISP

Heading text used in the main <h1> HTML tag (the logo) of the admin site.

default: Network administration

Title shown to users in the index page of the admin site.

default: []

Allows to pass a custom list of menu items to display in the admin menu.

If passed, overrides the default menu which is built by different openwisp modules.

The list should not include "home", "change password" and "log out", because those are automatically added and cannot be removed.

Example usage:

OPENWISP_ADMIN_MENU_ITEMS = [
    {'model': 'config.Device'},
    {'model': 'config.Template'},
    {'model': 'openwisp_users.User'},
    {
        'model': 'openwisp_radius.Accounting',
        'label': 'Radius sessions'  # custom label
    }
]

default: []

Allows to override the default CSS and favicon, as well as add extra <link> HTML elements if needed.

This setting overrides the default theme, you can reuse the default CSS or replace it entirely.

The following example shows how to keep using the default CSS, supply an additional CSS and replace the favicon.

Example usage:

OPENWISP_ADMIN_THEME_LINKS = [
    {'type': 'text/css', 'href': '/static/admin/css/openwisp.css', 'rel': 'stylesheet', 'media': 'all'},
    {'type': 'text/css', 'href': '/static/admin/css/custom-theme.css', 'rel': 'stylesheet', 'media': 'all'},
    {'type': 'image/x-icon', 'href': '/static/favicon.png', 'rel': 'icon'}
]

default: []

Allows to pass a list of strings representing URLs of custom JS files to load.

Example usage:

OPENWISP_ADMIN_THEME_JS = [
    '/static/custom-admin-theme.js',
]

• 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.

This package contains some utilities that are used in the automated builds of different OpenWISP modules.

This method can be used to mock a signal call inorder to easily verify that the signal has been called.

Usage example as a context-manager:

from openwisp_utils.tests import catch_signal

with catch_signal(openwisp_signal) as handler:
    model_instance.trigger_signal()
    handler.assert_called_once_with(
        arg1='value1',
        arg2='value2',
        sender=ModelName,
        signal=openwisp_signal,
    )

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

Shell script to automatically format Python code. It runs isort and black.

Shell script to run the following quality assurance checks:

• checkmigrations
• checkcommit
• checkendline
• checkpendingmigrations
• flake8 - Python code linter
• isort - Sorts python imports alphabetically, and seperated into sections
• black - Formats python code using a common standard

If a check requires a flag, it can be passed forward in the same way.

Usage example:

openwisp-qa-check --migration-path <path> --message <commit-message>

Any unneeded checks can be skipped by passing --skip-<check-name>

Usage example:

openwisp-qa-check --skip-isort

You can do multiple checkmigrations by passing the arguments with space-delimited string.

For example, this multiple checkmigrations:

checkmigrations --migrations-to-ignore 3 \
                --migration-path ./openwisp_users/migrations/ || exit 1

checkmigrations --migrations-to-ignore 2 \
                --migration-path ./tests/testapp/migrations/ || exit 1

Can be changed with:

openwisp-qa-check --migrations-to-ignore "3 2" \
        --migration-path "./openwisp_users/migrations/ ./tests/testapp/migrations/"

Ensures the latest migrations created have a human readable name.

We want to avoid having many migrations named like 0003_auto_20150410_3242.py.

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)"

If, for some reason, you wish to skip this QA check for a specific commit message you can add #noqa to the end of your commit message.

Usage example:

[qa] Improved #20

Simulation of a special unplanned case
#noqa

Ensures that a blank line is kept at the end of each file.

Ensures there django migrations are up to date and no new migrations need to be created.

It accepts an optional --migration-module flag indicating the django app name that should be passed to ./manage.py makemigrations, eg: ./manage.py makemigrations $MIGRATION_MODULE.

Install sqlite:

sudo apt-get install sqlite3 libsqlite3-dev

Install your forked repo:

git clone git://github.com/<your_fork>/openwisp-utils
cd openwisp-utils/
python setup.py develop

Install test requirements:

pip install -r requirements-test.txt

Create database:

cd tests/
./manage.py migrate
./manage.py createsuperuser

You can access the admin interface of the test project at http://127.0.0.1:8000/admin/.

Run tests with:

./runtests.py

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

See CHANGES.

See LICENSE.

See OpenWISP Support Channels.