help-tokens

4.0.0 verified Fri May 01 auth: no python

Django app for linking to help pages with short tokens. Current version 4.0.0 (released Feb 2024). Maintained as part of the Open edX ecosystem; irregular release cadence.

pip install help-tokens

Common errors

error ImportError: cannot import name 'get_help_url' from 'help_tokens' ↓

cause get_help_url is not exposed at the package level; it's in help_tokens.core.

fix

Use: from help_tokens.core import get_help_url

error ModuleNotFoundError: No module named 'help_tokens.app_config' ↓

cause AppConfig class moved from help_tokens.app_config to help_tokens.apps in v2.0.0.

fix

Use: from help_tokens.apps import HelpTokensAppConfig

error KeyError: 'HELP_TOKENS_BASE_URL' ↓

cause HELP_TOKENS_BASE_URL setting is required but not defined.

fix

Add to settings: HELP_TOKENS_BASE_URL = 'https://your-help-base-url.com/'

Warnings

breaking v4.0.0 dropped support for Python 3.11. Python 3.11 users must pin to <4.0.0. ↓

fix Use Python 3.12+ or install help-tokens==3.2.0.

breaking v2.0.0 dropped Python 3.5 support. Ensure your Python version is >=3.6. ↓

fix Upgrade Python to 3.6+.

deprecated The import 'from help_tokens import get_help_url' was deprecated in v2.0.0 and removed in v4.0.0. ↓

fix Use 'from help_tokens.core import get_help_url'.

gotcha Middleware must be placed after SessionMiddleware and AuthenticationMiddleware to access user context. ↓

fix Ensure middleware ordering: SessionMiddleware, AuthenticationMiddleware, then HelpTokenMiddleware.

Imports

HelpTokenMiddleware

from help_tokens.middleware import HelpTokenMiddleware

HelpUrl
```
from help_tokens.models import HelpUrl
```

get_help_url

wrong

from help_tokens import get_help_url

correct

from help_tokens.core import get_help_url

get_help_url is in help_tokens.core, not top-level

HelpTokensAppConfig

wrong

from help_tokens.app_config import HelpTokensAppConfig

correct

from help_tokens.apps import HelpTokensAppConfig

old imports from 'app_config' were renamed to 'apps' in v2.0.0

Quickstart

Add help_tokens to INSTALLED_APPS, include the middleware, and define HELP_TOKENS mapping.

# settings.py
INSTALLED_APPS = [
    ...
    'help_tokens',
]

MIDDLEWARE = [
    ...
    'help_tokens.middleware.HelpTokenMiddleware',
]

HELP_TOKENS_BASE_URL = os.environ.get('HELP_TOKENS_BASE_URL', 'http://example.com/help/')
HELP_TOKENS = {
    'student-dashboard': 'student/dashboard/',
}