AllianceAuth App Utilities

1.30.1 · active · verified Fri Apr 17

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.

Common errors

```
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: 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`).
```
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'}}`.

Install

pip install allianceauth-app-utils Install latest version

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'
#     }
# }

view raw JSON →