OpenWISP 2 Utilities
Project description
Python and Django utilities shared between different OpenWISP modules.
The admin theme requires Django >= 2.2.
Current features
Customized admin theme for OpenWISP modules
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
QA: logic and utilities to perform quality assurance checks across different modules
Project goals
Minimize code duplication among OpenWISP modules
Install stable version from pypi
Install from pypi:
pip install openwisp-utils
# install optional dependencies for tests (flake8 and isort)
pip install openwisp-utils[qa]
Install development version
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
Using the utilities in OpenWISP modules
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',
]
Using the admin_theme
Add openwisp_utils.admin_theme to INSTALLED_APPS in settings.py.
Admin mixins
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.
Using DependencyLoader and DependencyFinder
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']
DependencyFinder
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',
]
DependencyLoader
Add openwisp_utils.loaders.DependencyLoader 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'
],
},
},
]
Settings
OPENWISP_ADMIN_SITE_CLASS
default: openwisp_utils.admin_theme.admin.OpenwispAdminSite
If you need to use a customized admin site class, you can use this setting.
OPENWISP_ADMIN_SITE_TITLE
default: OpenWISP Admin
Title value used in the <title> HTML tag of the admin site.
OPENWISP_ADMIN_SITE_HEADER
default: OpenWISP
Heading text used in the main <h1> HTML tag (the logo) of the admin site.
OPENWISP_ADMIN_INDEX_TITLE
default: Network administration
Title shown to users in the index page of the admin site.
Quality Assurance checks
This package contains some common QA checks that are used the automated builds of different OpenWISP modules.
openwisp-utils-qa-checks
Shell script to run the following quality assurance checks:
flake8 - Python code linter
isort - Sorts python imports alphabetically, and seperated into sections
If a check requires a flag, it can be passed forward in the same way.
Usage example:
openwisp-utils-qa-checks --migration-path <path> --message <commit-message>
Any unneeded checks can be skipped by passing --skip-<check-name>
Usage example:
openwisp-utils-qa-checks --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-utils-qa-checks --migrations-to-ignore "3 2" \ --migration-path "./openwisp_users/migrations/ ./tests/testapp/migrations/"
checkmigrations
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/
checkcommit
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
checkendline
Ensures that a blank line is kept at the end of each file.
checkpendingmigrations
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.
Installing for development
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
Contributing
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
Write code and corresponding tests
Ensure that all tests pass and the test coverage does not decrease
Document your changes
Send a pull request
Changelog
See CHANGES.
License
See LICENSE.
Support
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for openwisp_utils-0.4.3-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8b568944c14b3ca945b53ef6b024b23b4a9395a915d72360a7ad9375140f9a49 |
|
MD5 | a572e2fef8cbbe0e14d3b9616d13f813 |
|
BLAKE2b-256 | 222250ca5a8218632168b2c2c3bedcba0de85fd18659b693de90069c4db8acf6 |