Boxine - bx_django_utils

Various Django utility functions

Quickstart

pip install bx_django_utils

Supported Django versions

bx_django_utils generally follows the support schedule of Django. The project is tested against officially supported Django versions and their respective supported CPython versions.

However, under special circumstances we may decide to pull support for a specific version early, e.g. if development of the library would be severely limited. Check our tox test matrix for a definitive answer.

Existing stuff

Here only a simple list about existing utilities. Please take a look into the sources and tests for deeper informations.

bx_django_utils.admin_extra_views

Django Admin extra views: https://github.com/boxine/bx_django_utils/blob/master/bx_django_utils/admin_extra_views/README.md

bx_django_utils.admin_extra_views.admin_config

Activate "ExtraViewAdminSite" by set this as default admin site

• CustomAdminConfig() - Change Django Admin Site to ExtraViewAdminSite for the extra views.

bx_django_utils.admin_extra_views.apps

• AdminExtraViewsAppConfig() - App config to auto discover all extra views.

bx_django_utils.admin_extra_views.conditions

• only_staff_user() - Pass only active staff users. The default condition for all admin extra views.

bx_django_utils.admin_extra_views.datatypes

• AdminExtraMeta() - Stores information for pseudo app and pseudo models.
• PseudoApp() - Represents information about a Django App. Instance must be pass to @register_admin_view()

bx_django_utils.admin_extra_views.management.commands.admin_extra_views

• Command() - Manage command "admin_extra_views": Info about registered admin extra views

bx_django_utils.admin_extra_views.registry

• AdminExtraViewRegistry() - Hold all information about all admin extra views to expand urls and admin app list.
• register_admin_view() - Decorator to add a normal view as pseudo App/Model to the admin.

bx_django_utils.admin_extra_views.site

• ExtraViewAdminSite() - AdminSite that injects registered extra views into the admin app list.

bx_django_utils.admin_extra_views.tests.test_admin_extra_views

• AdminExtraViewsTestCase() - Integrations tests for Admin Extra Views.

bx_django_utils.admin_extra_views.utils

• iter_admin_extra_views_urls() - Iterate over all registered admin extra view urls.
• reverse_admin_extra_view() - Get the URL of a Admin Extra View, e.g.: url=reverse_admin_extra_view(YouAdminExtraView)

bx_django_utils.admin_extra_views.views

• Redirect2AdminExtraView() - Redirect to a Admin Extra Views.

bx_django_utils.admin_utils.admin_urls

Helpers to build Admin URLs

• admin_change_url() - Shortcut to generate Django admin "change" url for a model instance.
• admin_changelist_url() - Shortcut to generate Django admin "changelist" url for a model or instance.
• admin_delete_url() - Shortcut to generate Django admin "delete" url for a model instance.
• admin_history_url() - Shortcut to generate Django admin "history" url for a model instance.
• admin_model_url() - Build Admin change, add, changelist, etc. links with optional filter parameters.

bx_django_utils.admin_utils.filters

• DecoratedSimpleListFilter() - Like SimpleListFilter but filters can be registered via register_list_filter() decorator.
• ExistingCountedListFilter() - Advanced SimpleListFilter that list only existing filter values with counts.
• NotAllSimpleListFilter() - Similar to SimpleListFilter, but don't add "All" choice.
• SimpleYesNoListFilter() - Base for Yes/No change list filters where:
• YesNoListFilter() - Quick way to create a Yes/No change list filter.
• register_list_filter() - Decorator to register a filter method in a DecoratedSimpleListFilter.

bx_django_utils.admin_utils.log_entry

Helper functions around Django's admin LogEntry model.

• create_log_entry() - Helper to create LogEntry entries for a model instance.
• get_change_message_strings() - Get LogEntry change messages as plain strings build by LogEntry.get_change_message().
• get_log_entry_qs() - Get a QuerySet of LogEntry objects, with optional filtering by model, object ID, and action flag.
• get_log_message_data() - Get LogEntry change messages data structure as list.
• validate_action_flag() - Validate that the action flag is one of the allowed values.

bx_django_utils.approve_workflow

Base model/admin/form classes to implement a model with draft/approve versions workflow

bx_django_utils.approve_workflow.admin

• BaseApproveModelAdmin() - Base admin class for a draft/approve Model

bx_django_utils.approve_workflow.forms

• PublishAdminForm() - Activate models REQUIRED_FIELDS_PUBLIC on approve

bx_django_utils.approve_workflow.models

• BaseApproveModel() - Base model class for approve models and this relation models.
• BaseApproveWorkflowModel() - Base model for approve workflow models.

bx_django_utils.cached_dataclasses

• CachedDataclassBase() - A Base dataclass that can be easy store/restore to Django cache.

bx_django_utils.data_types.gtin

ModelField, FormField and validators for GTIN/UPC/EAN numbers

bx_django_utils.data_types.gtin.form_fields

• GtinFormField() - Form field with GTIN validator.

bx_django_utils.data_types.gtin.model_fields

• GtinModelField() - GTIN model field

bx_django_utils.data_types.gtin.validators

• GtinValidator() - Validate GTIN number
• validate_gtin() - It's the same as stdnum.ean.validate() but also accept ISBN-10

bx_django_utils.db_table_info.admin_views

• DatabaseTableInfoBaseView() - A base admin extra view to display database table information for PostgreSQL databases.

bx_django_utils.dbperf.cursor

• RecordingCursorWrapper() - An implementation of django.db.backends.utils.CursorWrapper.

bx_django_utils.dbperf.query_recorder

• SQLQueryRecorder() - A context manager that allows recording SQL queries executed during its lifetime.

bx_django_utils.feature_flags

Feature flags: https://github.com/boxine/bx_django_utils/blob/master/bx_django_utils/feature_flags/README.md

bx_django_utils.feature_flags.admin_views

• ManageFeatureFlagsBaseView() - Base admin extra view to manage all existing feature flags in admin.

bx_django_utils.feature_flags.data_classes

• FeatureFlag() - A feature flag that persistent the state into django cache/database.

bx_django_utils.feature_flags.test_utils

• FeatureFlagTestCaseMixin() - Mixin for TestCase that will change FeatureFlag entries. To make the tests atomic.
• get_feature_flag_states() - Collects information about all registered feature flags and their current state.

bx_django_utils.feature_flags.utils

• if_feature() - A decorator that only executes the decorated function if the given feature flag is enabled.

bx_django_utils.filename

• clean_filename() - Convert filename to ASCII only via slugify.
• filename2human_name() - Convert filename to a capitalized name.

bx_django_utils.generic_model_filter.admin_views

Generic "AdminExtraView" view to filter accessible model by any field value.

• GenericModelFilterBaseView() - Base "AdminExtraView" to add this view to the admin interface via @register_admin_view().

bx_django_utils.http

• build_url_parameters() - Return an encoded string of all given parameters.

bx_django_utils.humanize.pformat

• pformat() - Better pretty-print-format using DjangoJSONEncoder with fallback to pprint.pformat()

bx_django_utils.humanize.time

• human_timedelta() - Converts a time duration into a friendly text representation. (X ms, sec, minutes etc.)

bx_django_utils.json_utils

• make_json_serializable() - Convert value to a JSON serializable value, with convert callback for special objects.
• to_json() - Convert value to JSON via make_json_serializable() and DjangoJSONEncoder()

bx_django_utils.models.color_field

• ColorModelField() - Hex color model field, e.g.: "#0055ff" (It's not a html color picker widget)
• HexColorValidator() - Hex color validator (seven-character hexadecimal notation, e.g.: "#0055ff")

bx_django_utils.models.get_models4user

• SelectModelForm() - Form to select a model that the user can "view"
• get_user_model_choices() - Build a form choices list with all models the given user can "view" | "add" | "change" | "delete" etc.
• iter_user_models() - Filter models for the given user.

bx_django_utils.models.manipulate

Utilities to manipulate objects in database via models:

• CreateOrUpdateResult() - Result object returned by create_or_update2() with all information about create/save a model.
• FieldUpdate() - Information about updated model field values. Used for CreateOrUpdateResult.update_info
• InvalidStoreBehavior() - Exception used in create_or_update() if "store_behavior" contains not existing field names.
• create() - Create a new model instance with optional validate before create.
• create_or_update() - Create a new model instance or update a existing one. Deprecated! Use: create_or_update2()
• create_or_update2() - Create a new model instance or update a existing one and returns CreateOrUpdateResult instance
• update_model_field() - Default callback for create_or_update2() to set a changed model field value and expand CreateOrUpdateResult

bx_django_utils.models.meta

• get_field_choices() - Build choices to select model fields. Use the verbose name of the field and handle related fields, too.

bx_django_utils.models.queryset_utils

• remove_filter() - Remove an applied .filter() from a QuerySet
• remove_model_filter() - Remove an applied .filter() from a QuerySet if it contains references to the specified model

bx_django_utils.models.timetracking

• TimetrackingBaseModel() - Abstract base model that will automaticly set create/update Datetimes.

bx_django_utils.stacktrace

• StackTrace() - Built-in mutable sequence.
• StacktraceAfter() - Generate a stack trace after a package was visited.
• get_stacktrace() - Returns a StackTrace object, which is a list of FrameInfo objects.

bx_django_utils.templatetags.accessors

• dict_get() - Returns the wanted member of a dict-like container, or an empty string

bx_django_utils.templatetags.humanize_time

• human_duration() - Verbose time since template tag, e.g.: <span title="Jan. 1, 2000, noon">2.0 seconds</span>

bx_django_utils.test_utils

Utilities / helper for writing tests.

bx_django_utils.test_utils.assert_queries

• AssertQueries() - Assert executed database queries: Check table names, duplicate/similar Queries.

bx_django_utils.test_utils.cache

• ClearCacheMixin() - TestCase mixin to clear the Django cache in setUp/tearDown
• MockCache() - Mock Django cache backend, so it's easy to check/manipulate the cache content

bx_django_utils.test_utils.content_types

• ContentTypeCacheFixMixin() - TestCase mixin to fill the ContentType cache to avoid flaky database queries.

bx_django_utils.test_utils.datetime

• MockDatetimeGenerator() - Mock django timezone.now() with generic time stamps in tests.

bx_django_utils.test_utils.fixtures

Utilities to manage text fixtures in JSON files.

• BaseFixtures() - Base class for JSON dump fixtures.
• FixturesRegistry() - Registry to collect a list of all existing fixture classes.
• RenewAllFixturesBaseCommand() - A base Django manage command to renew all existing fixture JSON dump files
• SerializerFixtures() - Helper to store/restore model instances serialized into a JSON file.
• autodiscover() - Register all fixtures by import all /fixtures//*.py files

bx_django_utils.test_utils.forms

• AssertFormFields() - Helper to check the existing form fields.

bx_django_utils.test_utils.html_assertion

• HtmlAssertionMixin() - Unittest mixin class with useful assertments around Django test client tests
• assert_html_response_snapshot() - Assert a HttpResponse via snapshot file using assert_html_snapshot() from bx_py_utils.
• get_django_name_suffix() - Returns a short Django version string, useable for snapshot "name_suffix" e.g.: "django42"

bx_django_utils.test_utils.log_entry

• get_django_log_entries() - Collect LogEntry data for tests.

bx_django_utils.test_utils.model_clean_assert

• AssertModelCleanCalled() - Context manager for assert that full_clean() was called for every model instance.
• CleanMock() - Track if full_clean() was called.

bx_django_utils.test_utils.model_primary_key

• deterministic_primary_key() - Context manager for unittests to use deterministic primary key for a model creation.

bx_django_utils.test_utils.playwright

Use Playwright in Unittest + Fast Django user login

• PlaywrightConfig() - PlaywrightTestCase config from environment (PWBROWSER, PWHEADLESS, PWSKIP, PWSLOWMO)
• PlaywrightTestCase() - StaticLiveServerTestCase with helpers for writing frontend tests using Playwright.

bx_django_utils.test_utils.users

• assert_permissions() - Check user permissions.
• assert_user_properties() - Check a user instance with all properties and password (optional)
• filter_permission_names() - Generate a Permission model query filtered by names, e.g.: ['<app_label>.', ...]
• make_max_test_user() - Create a test user with all permissions except the {exclude_permissions} ones.
• make_minimal_test_user() - Create a test user and set given permissions.
• make_test_user() - Create a test user and set given permissions.

bx_django_utils.translation

• FieldTranslation() - Dict-like container that maps language codes to a translated string.
• TranslationField() - A field designed to hold translations for a given set of language codes.
• TranslationFieldAdmin() - Provides drop-in support for ModelAdmin classes that want to display TranslationFields
• TranslationFormField() - Default form field for TranslationField.
• TranslationSlugField() - A unique translation slug field, useful in combination with TranslationField()
• create_or_update_translation_callback() - Callback for create_or_update2() for TranslationField, that will never remove existing translation.
• expand_languages_codes() - Build a complete list if language code with and without dialects.
• get_user_priorities() - Collect usable language codes the current user
• make_unique() - Flat args and remove duplicate entries while keeping the order intact.
• merge_translations() - Merge two FieldTranslation and ignore all empty/None values, e.g.:
• remove_empty_translations() - Remove all empty/None from a FieldTranslation, e.g.:
• user_language_priorities() - Returns the order in which to attempt resolving translations of a FieldTranslation model field.
• validate_unique_translations() - Deny creating non-unique translation: Creates ValidationError with change list search for doubled entries.

bx_django_utils.user_timezone

Automatic local user timezone: https://github.com/boxine/bx_django_utils/blob/master/bx_django_utils/user_timezone/README.md

bx_django_utils.user_timezone.apps

• UserTimezoneAppConfig() - Django app to set the user local time zone.

bx_django_utils.user_timezone.humanize

• human_timezone_datetime() - Render a datetime with timezone information.

bx_django_utils.user_timezone.middleware

• InvalidUserTimeZone() - Inappropriate argument value (of correct type).
• UserTimezoneMiddleware() - Activate Timezone by "UserTimeZone" cookie
• validate() - Validate the UserTimeZone cookie value.

bx_django_utils.user_timezone.templatetags.user_timezone

• humane_timezone_dt() - Template filter to render a datetime with timezone information.

bx_django_utils.version

• DetermineVersionCommand() - Write application version determined from git as a command
• get_version() - Get version of this application. First try to read it from file, then determine from git.

bx_django_utils.view_utils.dynamic_menu_urls

• DynamicViewMenu() - Simple storage for store information about views/urls to build a menu.

start development

At least uv is needed. Install e.g.: via pipx:

apt-get install pipx
pipx install uv

you should be able to then do

make install
make playwright-install

and validate everything works with make test

For other options, you can check out our makefile:

~$ git clone https://github.com/boxine/bx_django_utils.git
~$ cd bx_django_utils
~/bx_django_utils$ make
help                       List all commands
install                    Install via "uv" (Used system installed "uv" tool, e.g.: "pipx install uv")
update-requirements        Update requirements
lint                       Check/fix code style by run: "ruff check --fix"
nox-list                   List all available nox sessions
nox                        Run tests via nox with all environments and create coverage report
test                       Run tests
coverage-report            Creates coverage report
coverage                   Run tests with coverage (Use better "nox" target)
update-test-snapshot-files Update all snapshot files (by remove and recreate all snapshot files)
update-test-migrations     Update migration files from the test project by recreating them
update-readme              Update README.md (will be also done in tests)
mypy                       Run mypy
docker-test                Run tests in docker
pip-audit                  Run https://github.com/pypa/pip-audit
publish                    Release new version to PyPi
makemessages               Make and compile locales message files
start-dev-server           Start Django dev. server with the test project
clean                      Remove created files from the test project
playwright-install         Install test browser for Playwright tests
playwright-inspector       Run Playwright inspector
playwright-tests           Run only the Playwright tests

You can start the test project with the Django developing server, e.g.:

~/bx_django_utils$ make start-dev-server

This is a own manage command, that will create migrations files from our test app, migrate, collectstatic and create a super user if no user exists ;)

If you like to start from stretch, just delete related test project files with:

~/bx_django_utils$ make clean

...and start the test server again ;)

Create a release

• Increase verion number in bx_django_utils/__init__.py
• Create pull request
• After merge, call: make publish

License

MIT. Patches welcome!

About us

We’ve been rethinking the listening experience for kids and have created an ecosystem where haptic and listening experience are combined via smart technology - the Toniebox.

We are constantly looking for engineers to join our team in different areas. If you’d be interested in contributing to our platform, have a look at: https://tonies.com/jobs/

Links

• https://pypi.org/project/bx-django-utils/