Python and Django utilities shared between different OpenWISP modules.
Table of Contents:
- Current features
- Project goals
- Install stable version from pypi
- Install development version
- Using the utilities in OpenWISP modules
- Installing for development
- Contributing
- Changelog
- License
- Support
- Customized admin theme for OpenWISP modules
- TimeStamped models and mixins which add self-updating
created
andmodified
fields. - UUIDModel: base model with a UUID4 primary key
- 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
- 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 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',
# all-auth
'django.contrib.sites',
'allauth',
'allauth.account',
'allauth.socialaccount',
'django_extensions',
# openwisp2 modules
'openwisp_users',
# admin
'django.contrib.admin',
]
For using the customized admin theme,
- Make sure you've added
openwisp_utils.admin_theme
toINSTALLED_APPS
insettings.py
- Add the following into your
urls.py
file which containsadmin
urls.
from django.conf.urls import include, url
from openwisp_utils.admin_theme.admin import admin, openwisp_admin
openwisp_admin()
urlpatterns = [
# other url patterns
url(r'^admin/', include(admin.site.urls)),
]
- TimeReadonlyAdminMixin: Admin mixin which adds two readonly fields
created
andmodified
. This is an admin mixin for models inheritingTimeStampedEditableModel
which adds the fieldscreated
andmodified
to the database.
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.staticfiles.DependencyFinder
to
template loaders
in settings.py
as shown below.
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'OPTIONS': {
'loaders': [
'django.template.loaders.filesystem.Loader',
'django.template.loaders.app_directories.Loader',
'openwisp_utils.loaders.DependencyLoader',
],
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
'openwisp_utils.admin_theme.context_processor.menu_items'
],
},
},
]
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': [
'django.template.loaders.filesystem.Loader',
'django.template.loaders.app_directories.Loader',
'openwisp_utils.loaders.DependencyLoader',
],
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
'openwisp_utils.admin_theme.context_processor.menu_items'
],
},
},
]
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
}
]
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 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)"
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
- Announce your intentions in the OpenWISP Mailing List and open relavant issues using the issue tracker
- Fork this repo and install the project following the instructions
- Follow PEP8, Style Guide for Python Code
- Write code and corresponding tests
- Ensure that all tests pass and the test coverage does not decrease
- Document your changes
- Send a pull request
See CHANGES.
See LICENSE.