AllianceAuth App Utilities

1.30.1 verified Fri Apr 17 auth: no python

AllianceAuth App Utilities (allianceauth-app-utils) is a Python library providing commonly used utilities and helpers for rapid development of Alliance Auth applications. It streamlines common tasks like handling app settings, user roles, and Django views. The current version is 1.30.1, with updates typically coinciding with or shortly after Alliance Auth and Django releases, maintaining active development.

pip install allianceauth-app-utils

Common errors

error ModuleNotFoundError: No module named 'allianceauth.utils.app_settings' ↓

cause Attempting to import utilities from the deprecated `allianceauth.utils` path, which was split into `allianceauth-app-utils`.

fix

Update imports to use the correct allianceauth_app_utils package. For example, change from allianceauth.utils.app_settings import get_app_settings to from allianceauth_app_utils.app_settings import get_app_settings.

error ERROR: Package 'allianceauth-app-utils' requires Django>=4.2.0, but you have Django X.Y.Z which is incompatible. ↓

cause Your current Django version is older than 4.2, which is no longer supported by `allianceauth-app-utils` versions >= 1.29.0.

fix

Upgrade your Django installation to version 4.2 or newer (pip install Django>=4.2,<5.0). Alternatively, if you must use an older Django, pin allianceauth-app-utils to a compatible version (e.g., pip install allianceauth-app-utils<1.29.0).

error ImproperlyConfigured: This version of allianceauth-app-utils requires Python >= 3.9.0. You are running X.Y.Z. ↓

cause Your current Python environment is older than 3.9, which is no longer supported by `allianceauth-app-utils` versions >= 1.28.0.

fix

Upgrade your Python environment to version 3.9 or newer. Alternatively, if you must use an older Python, pin allianceauth-app-utils to a compatible version (e.g., pip install allianceauth-app-utils<1.28.0).

Warnings

breaking Versions of `allianceauth-app-utils` >= 1.29.0 require Django >= 4.2. Support for Django 3.2 was dropped. Ensure your Django version is compatible. ↓

fix Upgrade your Django project to Django 4.2 or newer, or pin `allianceauth-app-utils` to a version < 1.29.0 (e.g., `allianceauth-app-utils<1.29.0`).

breaking Versions of `allianceauth-app-utils` >= 1.28.0 require Python >= 3.9. Support for Python 3.8 was dropped. Ensure your Python environment meets this requirement. ↓

fix Upgrade your Python environment to 3.9 or newer, or pin `allianceauth-app-utils` to a version < 1.28.0 (e.g., `allianceauth-app-utils<1.28.0`).

breaking Prior to version 1.0.0, many utilities were part of the main `allianceauth` package (`allianceauth.utils`). All imports for this library should now come from `allianceauth_app_utils`. ↓

fix Update all imports from `allianceauth.utils.*` to `allianceauth_app_utils.*` (e.g., `from allianceauth.utils.app_settings import get_app_settings` becomes `from allianceauth_app_utils.app_settings import get_app_settings`).

gotcha Custom settings for your app, retrieved by `get_app_settings()`, must be defined in your project's `settings.py` under the `APP_SETTINGS` dictionary. If not defined, `get_app_settings` will return an empty dictionary or default values. ↓

fix Add a dictionary entry for your app label within `APP_SETTINGS` in your `settings.py`. Example: `APP_SETTINGS = {'my_app': {'MY_SETTING': 'value'}}`.

Imports

get_app_settings

wrong

from allianceauth.utils.app_settings import get_app_settings

correct

from allianceauth_app_utils.app_settings import get_app_settings

Old path from when utilities were part of the main Alliance Auth package (prior to v1.0.0).

AuthRequiredMixin

from allianceauth_app_utils.views import AuthRequiredMixin

BaseAuthAppConfig

from allianceauth_app_utils.base_roles import BaseAuthAppConfig

register_permissions_delegate

from allianceauth_app_utils.signals import register_permissions_delegate

Quickstart

This quickstart demonstrates using `AuthRequiredMixin` to create a view that requires Alliance Auth authentication and retrieves app-specific settings via `get_app_settings`. Remember to configure `APP_SETTINGS` in your Django project's `settings.py`.

# my_app/views.py
from django.shortcuts import render
from django.views import View
from allianceauth_app_utils.app_settings import get_app_settings
from allianceauth_app_utils.views import AuthRequiredMixin

class MyProtectedView(AuthRequiredMixin, View):
    # Optional: Define permissions required for this view
    # required_permissions = ['my_app.can_view_dashboard']

    def get(self, request):
        # Replace 'my_app' with your actual Django app label
        # Ensure APP_SETTINGS is configured in your project's settings.py
        app_settings = get_app_settings('my_app') 
        example_setting = app_settings.get('MY_EXAMPLE_SETTING', 'Default Value')
        context = {
            'username': request.user.username,
            'example_setting': example_setting
        }
        return render(request, 'my_app/dashboard.html', context)

# --- Example settings.py entry ---
# APP_SETTINGS = {
#     'my_app': {
#         'MY_EXAMPLE_SETTING': 'Configured Value From Settings'
#     }
# }