Contrib Apps

Various, optional apps for commonly needed features of a web site or web application.

Version: 0.4.0-d

Contributing or contrib apps provide pre-defined functionality. Some of this functionality may be used as is, while other features require integration or customization to be effectively employed.

Accounts

Various apps for managing user accounts.

Component Reference: Accounts

Account Admin

The user admin app provides a SuperDjango UI for working with users and groups.

Component Reference: Account Admin

Abstract

The user admin app provides a SuperDjango UI for working with users and groups.

Install

Add superdjango.contrib.accounts.admin.apps.DefaultConfig`,` to ``INSTALLED_APPS.

Note

The SuperDjango UI system is required and UsersMenu must be registered.

Authentication

Basic/standard user authentication via user name and/or email.

Component Reference: Authentication

backends

class superdjango.contrib.accounts.auth.backends.CaseInsensitiveModelBackend

Bases: django.contrib.auth.backends.ModelBackend

Validate a user with a username that ignores the case of the submitted user name.

Warning

Use this backend with caution. While it allows a user to authenticate with a case-insensitive variation of his or her user name, it can produce errors (MultipleObjectsExist, for example) if you don’t also check for case-insensitive user names upon user account creation.

authenticate(request, username=None, password=None, **kwargs)

Authenticate with iexact.

class superdjango.contrib.accounts.auth.backends.EmailBackend

Bases: object

Allow the user to authenticate using an email address.

# settings.py
AUTHENTICATION_BACKENDS = [
    'superdjango.accounts.backends.EmailBackend',
    'django.contrib.auth.backends.ModelBackend',
]

authenticate(username=None, password=None, **kwargs)

Authenticate against an email address.

get_user(user_id=None)

Comply with backend API.

forms

class superdjango.contrib.accounts.auth.forms.AuthenticationForm(request=None, *args, **kwargs)

Bases: django.contrib.auth.forms.AuthenticationForm

User login form with “remember me” option.

middleware

class superdjango.contrib.accounts.auth.middleware.LoginRequiredMiddleware

Bases: object

Require a user login for the whole site, except certain URLs.

# settings.py
MIDDLEWARE = [
    # ...
    'superdjango.accounts.middleware.LoginRequiredMiddleware',
]

Note

This requires django.contrib.auth.middleware.AuthenticationMiddleware in MIDDLEWARE_CLASSES and django.core.context_processors.auth in your TEMPLATES configuration.

process_request(request)

Check the request for an authenticated user.

If the user is unauthenticated, a redirect is issued to the LOGIN_URL plus the current path using the REDIRECT_FIELD_NAME.

Raise

NoUserInRequest

Raises

NoUserInRequest when django.contrib.auth.middleware.AuthenticationMiddleware` is not in MIDDLEWARE_CLASSES.

views

These views wrap Django’s authentication views to provide template output. This also allows ad hoc customization if needed.

class superdjango.contrib.accounts.auth.views.Login(**kwargs)

Bases: django.contrib.auth.views.LoginView

Login form and redirect on successful authentication. Supports “remember me” functionality when SUPERDJANGO_REMEMBER_ME_ENABLED is True.

form_valid(form)

With valid submit, optionally set session expiration to SUPERDJANGO_USER_REMEMBER_ME_SECONDS. If history_callback is callable, the successful login is recorded..

from_invalid(form)

If history_callback is callable, the unsuccessful login attempt is recorded.

get_context_data(**kwargs)

Add accounts_password_reset URL as cancel_url and cancel_text, if available.

get_form_class()

The default form class is used unless SUPERDJANGO_USER_REMEMBER_ME_ENABLED is True.

get_password_reset_url()

Get the URL for password resets.

Return type

str | None

get_redirect_url()

Override to return accounts_login_redirect (if it exists) when no originating URL has been provided.

Note

get_success_url() behaves as usual.

history_class = None

A model that may be used to record both successful and unsuccessful login attempts. This class must define three (3) fields:

1. added_dt: The date and time the record was created, set to auto_now_add.

2. success: A boolean indicating success or failure.

3. user: A reference to AUTH_USER_MODEL that is the subject of the login.

max_attempts = None

The maximum number of login attempts (int) before a user account is marked inactive. Requires a history_class.

max_minutes = None

The number of minutes (int) between login attempts.

password_reset_text = 'Forgot your password?'

The text to display for the password reset URL, when available.

password_reset_url = None

The URL if any that allows a user to reset his/her password. Tip: Use reverse_lazy().

class superdjango.contrib.accounts.auth.views.LoginRedirect(**kwargs)

Bases: superdjango.views.redirects.RedirectView

Intelligently redirect the user based on preferences or global settings.

get_redirect_url(*args, **kwargs)

Get the user’s preferred redirect if possible or the LOGIN_REDIRECT_URL by default.

class superdjango.contrib.accounts.auth.views.Logout(**kwargs)

Bases: django.contrib.auth.views.LogoutView

Log the user out.

get_context_data(**kwargs)

Add login_url, if available.

Avatars

Support for user avatars.

Component Reference: Avatars

templatetags

utils

superdjango.contrib.accounts.avatars.utils.get_gravatar_url(email, size=60)

Get the Gravatar URL for the given email address.

Parameters

• email (str) – The email address.

• size (int) – The desired size of the image.

Return type

str

User Impersonation

Allow authenticated and authorized users to impersonate another user.

Component Reference: User Impersonation

admin

class superdjango.contrib.accounts.impersonation.admin.BaseImpersonationHistoryAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Base model admin for ImpersonationHistoryModel.

get_fields(request, obj=None)

Hook for specifying fields.

get_list_display(request)

Return a sequence containing the fields to be displayed on the changelist.

get_list_filter(request)

Return a sequence containing the fields to be displayed as filters in the right sidebar of the changelist page.

get_readonly_fields(request, obj=None)

Hook for specifying custom readonly fields.

constants

superdjango.contrib.accounts.impersonation.constants.IMPERSONATION_FOR_ID = '_impersonation_for_id'

The name of the session key used to identify the user being impersonated.

superdjango.contrib.accounts.impersonation.constants.IMPERSONATION_PREVIOUS_URL = '_impersonation_previous_url'

The name of the session key used to send the impersonator back to the original URL after impersonation ends.

superdjango.contrib.accounts.impersonation.constants.IMPERSONATION_SESSION_KEY = '_impersonation_session_key'

The name of the session key used to identify the current impersonation session.

context_processors

Library of context processors.

superdjango.contrib.accounts.impersonation.context_processors.user_is_allowed_to_impersonate(request)

Add a flag which indicates whether the current user is allowed to impersonate another user.

Parameters

request – The request instance is not used.

Type

request: object

Return type

dict

forms

class superdjango.contrib.accounts.impersonation.forms.UserImpersonationSearchForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None)

Bases: django.forms.forms.Form

Collect input for searching users to be listed for impersonation..

middleware

class superdjango.contrib.accounts.impersonation.middleware.UserImpersonationMiddleware(get_response)

Bases: object

Facilitate user impersonation.

__init__(get_response)

Initialize self. See help(type(self)) for accurate signature.

models

class superdjango.contrib.accounts.impersonation.models.ImpersonationHistoryModel(*args, **kwargs)

Bases: superdjango.db.timed.models.TimedModel

Base class for creating an impersonation log.

Parameters

• timer_elapsed_seconds (PositiveIntegerField) – Total seconds elapsed from start to end.

• timer_is_running (BooleanField) – Indicates whether the timer is running.

• timer_start_dt (DateTimeField) – Date and time the timer was started.

• timer_stop_dt (DateTimeField) – Date and time the timer was stopped.

• impersonation_by_id (ForeignKey) – The user that impersonated another user.

• impersonation_for_id (ForeignKey) – The user being impersonated.

• session_key (CharField) – The session key of the impersonation.

• status (CharField) – The current status of the impersonation.

classmethod start(impersonation_by, impersonation_for, session_key)

Create a log entry for impersonation.

Parameters

• impersonation_by (AUTH_USER_MODEL) – The user doing the impersonation.

• impersonation_for (AUTH_USER_MODEL) – The user being impersonated.

• session_key (str) – The Django session key.

Return type

ImpersonationHistoryModel

stop()

Close the log entry.

utils

superdjango.contrib.accounts.impersonation.utils.generate_session_key()

Generate a session key to identify an impersonation.

Return type

str

superdjango.contrib.accounts.impersonation.utils.get_user_impersonation_model()

Get the model used to log impersonation history.

Return type

ImpersonationHistoryModel | None

superdjango.contrib.accounts.impersonation.utils.user_is_allowed_to_impersonate(user)

Determine whether the given user is allowed to impersonate another user.

Parameters

user (AUTH_USER_MODEL) – The user instance to be checked.

Return type

bool

views

class superdjango.contrib.accounts.impersonation.views.ImpersonationHelp(**kwargs)

Bases: superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

get_breadcrumbs()

Get the breadcrumbs for the view.

Return type

Breadcrumbs

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.accounts.impersonation.views.ImpersonationViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

class superdjango.contrib.accounts.impersonation.views.ListUsersForImpersonation(**kwargs)

Bases: superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

get_breadcrumbs()

Get the breadcrumbs for the view.

Return type

Breadcrumbs

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.accounts.impersonation.views.SearchUsersForImpersonation(**kwargs)

Bases: superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.forms.FormView

form_class

alias of superdjango.contrib.accounts.impersonation.forms.UserImpersonationSearchForm

form_valid(form)

Process a valid form and redirect to success URL.

get_breadcrumbs()

Get the breadcrumbs for the view.

Return type

Breadcrumbs

get_context_data(**kwargs)

Add breadcrumbs to the context.

get_success_url()

Get the URL to which the user should be sent on successful form submit.

Return type

str

class superdjango.contrib.accounts.impersonation.views.StartImpersonationRedirect(**kwargs)

Bases: superdjango.views.access.AccessMixin, superdjango.views.redirects.RedirectView

get_redirect_url(*args, **kwargs)

Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

class superdjango.contrib.accounts.impersonation.views.StopImpersonationRedirect(**kwargs)

Bases: superdjango.views.access.AccessMixin, superdjango.views.redirects.RedirectView

get_redirect_url(*args, **kwargs)

Return the URL redirect to. Keyword arguments from the URL pattern match generating the redirect request are provided as kwargs to this method.

Password Management

Allow users to self-manage passwords.

Component Reference: Password Management

forms

class superdjango.contrib.accounts.passwords.forms.PasswordResetForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None)

Bases: django.contrib.auth.forms.PasswordResetForm

User password reset form a user name field.

get_users(email_or_username)

Also check the email argument as a user name argument.

models

Abstract models related to password management.

class superdjango.contrib.accounts.passwords.models.PasswordResetHistoryModel(*args, **kwargs)

Bases: django.db.models.base.Model

Record password reset attempts.

Parameters

• added_dt (AutoNowAddDateTimeField) – Date and time the record was created.

• email (EmailField) – The email address of the requested attempt.

• http_accept (CharField) – The HTTP accept header of the requested attempt.

• ip_address (GenericIPAddressField) – The IP address of the visitor.

• success (BooleanField) – Indicates a matching user was found.

• user_agent (CharField) – The user agent of the requested attempt.

• username (CharField) – The user name to which the reset pertains.

property label

Get a label for the record.

Return type

str

views

These views wrap Django’s authentication views to provide template output. This also allows ad hoc customization if needed.

class superdjango.contrib.accounts.passwords.views.PasswordChange(**kwargs)

Bases: django.contrib.auth.views.PasswordChangeView

Present and validate the password change view.

cancel_url = None

The URL to which the user is sent when cancelling the password change. Tip: use reverse_lazy().

get_cancel_url()

Get the cancel_url, or if one has not been specified, attempt to return accounts_profile.

Return type

str | None

get_context_data(**kwargs)

Attempt to add cancel_url.

get_success_url()

Get the user profile URL (accounts_profile) if possible or the URL for password change complete (accounts_password_change_complete).

class superdjango.contrib.accounts.passwords.views.PasswordChangeComplete(**kwargs)

Bases: django.contrib.auth.views.PasswordChangeDoneView

The default page to which users are sent after a password change has been completed.

class superdjango.contrib.accounts.passwords.views.PasswordReset(**kwargs)

Bases: django.contrib.auth.views.PasswordResetView

Enable password resets from the login form. This is step 1 of the process.

form_invalid(form)

Log unsuccessful password reset request when history_class is callable.

form_valid(form)

Log a successful password reset request when history_class is callable.

get_form_class()

Use the username form when username_enabled is True.

get_success_url()

Get the password reset submitted URL.

history_class = None

A model that may be used to record both successful and unsuccessful login attempts. This class must define six (6) fields:

1. added_dt: The date and time the record was created, set to auto_now_add.

2. email: The email address submitted with the request.

3. ip_address: A GenericIPAddressField. Not required.

4. success: A boolean indicating success or failure.

5. user_agent: A CharField. Not required.

6. username: A CharField. Not required.

max_attempts = 3

The maximum number of password reset attempts (int) before a user account is locked.

max_minutes = 30

The number of minutes (int) between max password reset attempts.

username_enabled = False

When True, the reset lookup will also attempt to find a given user name if one has been given.

class superdjango.contrib.accounts.passwords.views.PasswordResetComplete(**kwargs)

Bases: superdjango.views.templates.TemplateView

Display a page after the password reset has been completed. This is step 4 of the process if post reset login is not enabled.

class superdjango.contrib.accounts.passwords.views.PasswordResetConfirm(**kwargs)

Bases: django.contrib.auth.views.PasswordResetConfirmView

A user follows the password reset link to this page in order to reset his or her password. This is step 3 of the process.

get_success_url()

Get the complete (log in again) page or intelligent redirect depending upon post_reset_login.

class superdjango.contrib.accounts.passwords.views.PasswordResetSubmit(**kwargs)

Bases: superdjango.views.templates.TemplateView

Presents a page after a password reset request has been submitted. This is step 2 of the process.

class superdjango.contrib.accounts.passwords.views.PasswordsViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

User Profiles

Allow users to manage their account profiles.

Component Reference: User Profiles

forms

class superdjango.contrib.accounts.profiles.forms.ProfileForm(*args, **kwargs)

Bases: django.forms.models.ModelForm

A base form for user profiles based on the ProfileModel.

__init__(*args, **kwargs)

Initialize with a user keyword argument, add redirect and time zone choices, and set defaults.

clean_email()

Email addresses must be unique. This checks to see if the current address is different than the submitted address and makes sure a new address is not already taken.

clean_username()

User names must be unique. This checks to see if the current name is different than the submitted name and makes sure a new name is not already taken.

property fieldsets

Alias of get_fieldsets().

get_fieldsets()

Get the field sets to be included in the form.

Return type

list[superdjango.html.library.Fieldset]

property has_fieldsets

Indicates the form has fieldsets.

Return type

bool

save(commit=True)

Process user fields.

models

class superdjango.contrib.accounts.profiles.models.ProfileMixin

Bases: object

Establishes the API for user profiles.

property email

Aliased for the user’s email address.

classmethod for_user(user, create=False, profile_name='profile')

Get (or create) the profile for a given user.

Parameters

• user (AUTH_USER_MODEL) – The user.

• create (bool) – Indicates whether a profile should be created if one does not already exist.

• profile_name (str) – The related name of the profile field.

Return type

instance

Returns

An instance of a profile model for the user.

property full_name

Aliased for get_full_name().

property full_name_with_honorifics

Alias of get_full_name_with_honorifics().

get_form_class(request=None)

Get the form class to use for editing the profile.

Parameters

request (HttpRequest) – The current request instance.

get_full_name()

Get the full name of the user, or the user name if a full name is not available.

Return type

str

get_full_name_with_honorifics()

Get the full name of the user, including prefix and suffix, if available.

Return type

str

get_redirect_url()

Get the URL to which the user prefers to be redirected after logging in.

Return type

str

Note

By default, the settings.LOGIN_REDIRECT_URL is returned. The profile model may implement a user preference for the redirect.

get_sections()

Get the sections to display for profile detail.

Return type

list[ProfileSection]

get_thumbnail()

Get the thumbnail URL for the user’s avatar.

Return type

str

get_time_zone()

Get the timezone of the user. If unavailable, the default time zone should be returned.

Return type

str

Note

The profile model that uses this mixin should implement a field (or other means) of establishing the user’s time zone (using geo-location for example), defaulting to settings.TIME_ZONE only if a time zone preference is unavailable.

property has_thumbnail

Indicates the profile has a thumbnail image.

:rtype bool

property last_login

Alias for the user’s last login.

property redirect_url

Alias for get_redirect_url().

property sections

Alias for get_sections().

property thumbnail

Aliased for get_thumbnail().

property username

Aliased for the user’s username.

class superdjango.contrib.accounts.profiles.models.ProfileModel(*args, **kwargs)

Bases: superdjango.contrib.accounts.profiles.models.ProfileMixin, django.db.models.base.Model

An implementation of the profile mixin with sensible defaults.

Note

No fields with foreign keys are included.

This model extends the mixin to establishe some common profile attributes:

from superdjango.contrib.accounts.profiles.models import ProfileModel

class Profile(ProfileModel):

    user = models.OneToOneField(
        AUTH_USER_MODEL,
        help_text=_("The user account to which this profile is attached."),
        related_name="profile",
        verbose_name=_("user")
    )

    class Meta:
        verbose_name = _("User Profile")
        verbose_name_plural = _("User Profiles")

Parameters

• address (TextField) – Enter your mailing address.

• first_name (CharField) – Your given name.

• gravatar_enabled (BooleanField) – Use gravatar.com for your profile picture.

• last_name (CharField) – Your family name.

• middle_name (CharField) – Your middle name or initial.

• phone_number (CharField) – Enter your phone number.

• photo (FileField) – Upload a photo to use for your profile picture.

• prefix (CharField) – Enter a prefix to appear before your name or leave blank for nothing.

• suffix (CharField) – Enter a suffix to appear after your name or leave blank for nothing.

• redirect_to (CharField) – By default, go to this page after logging in.

• time_zone (CharField) – Select the timezone in which you reside or work.

get_form_class(request=None)

Get the form class to use for editing the profile.

Parameters

request (HttpRequest) – The current request instance.

get_full_name()

Get the full name of the user, or the user name if a full name is not available.

Return type

str

get_full_name_with_honorifics()

Get the full name of the user, including prefix and suffix, if available.

Return type

str

get_redirect_url()

Get the user’s redirect choice or the LOGIN_REDIRECT_URL if no choice has been made.

Return type

str

get_sections()

Get profile sections.

get_thumbnail()

Uses gravatar or an uploaded photo.

get_time_zone()

Get the time zone of the user or the default timezone.

Return type

str

property has_thumbnail

Determines a gravatar or photo is available.

property title

Automated object title for UI views.

class superdjango.contrib.accounts.profiles.models.ProfileSection(title)

Bases: object

Collects related profile fields together for display.

__init__(title)

Initialize self. See help(type(self)) for accurate signature.

add_item(label, value)

Add an item to the section.

Parameters

• label (str) – The label for the item, i.e. field’s verbose name.

• value – The value of the item.

Return type

ProfileSectionItem

class superdjango.contrib.accounts.profiles.models.ProfileSectionItem(label, value)

Bases: object

An individual field within a section.

__init__(label, value)

Initialize self. See help(type(self)) for accurate signature.

views

class superdjango.contrib.accounts.profiles.views.ProfileDetail(**kwargs)

Bases: superdjango.contrib.accounts.profiles.views.ProfileRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

Display the user profile for the current user.

get_breadcrumbs()

Get profile breadcrumbs.

get_context_data(**kwargs)

Add profile to the context.

class superdjango.contrib.accounts.profiles.views.ProfileRequiredMixin

Bases: superdjango.views.messages.MessageMixin, superdjango.views.access.AccessMixin

Use this to require a profile before proceeding.

auto_create = False

Indicates whether a profile should be created for the user if one does not exist.

check_other(request, *args, **kwargs)

Check whether a profile exists. Sets self.object as well. The auto_create option is passed to the profile model’s for_user() method, which means the profile may be created on the fly.

A typical approach to this would be to define auto_create (or SUPERDJANGO_AUTO_CREATE_PROFILE) as False for profile detail views and override to True for the profile update view. This allows profiles to be created as needed.

dispatch_other(request, message=None, redirect_url=None)

Returns a 404 response when raise_access_exception is True. Otherwise, this will send authenticated users to the update view (where a profile should be created by default) and unauthenticated users to the login page.

login_required = True

A login is always required for profile access.

class superdjango.contrib.accounts.profiles.views.ProfileUpdate(**kwargs)

Bases: superdjango.contrib.accounts.profiles.views.ProfileRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.crud.UpdateView

Facilitate self management of user profile data.

form_class

alias of superdjango.contrib.accounts.profiles.forms.ProfileForm

form_valid(form)

Save the record.

get_breadcrumbs()

Overridden to so that UpdateView breadcrumbs are not used.

get_cancel_url()

Send the user back to the profile view.

get_form(data=None, files=None, **kwargs)

Add the current user to form data.

get_form_class()

Get the form class from the model or using the default form_class attribute of the view.

get_object()

Overridden to return the current profile without a lookup key. self.object is defined in the ProfileRequiredMixin.

get_subtitle()

Provide a default subtitle for the page.

class superdjango.contrib.accounts.profiles.views.ProfileViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

Account Utils

Utilities for managing user accounts.

Component Reference: Account Utils

library

superdjango.contrib.accounts.utils.library.get_profile_model()

Get the user profile model, if any.

Returns

The profile class or None.

Raises

ImproperlyConfigured, ValueError

Note

This utility is intentionally located outside of the profiles app to reduce dependency on that app.

superdjango.contrib.accounts.utils.library.get_user_profile(user)

Get a user profile.

Parameters

user (AUTH_USER_MODEL) – The user instance.

Return type

SUPERDJANGO_USER_PROFILE_MODEL | None

Tip

A user field must exist on the profile model.

Note

This utility is intentionally located outside of the profiles app to reduce dependency on that app.

Password Management

Additional views for user account management.

Component Reference: Password Management

viewsets

class superdjango.contrib.accounts.views.viewsets.AccountsViewSet(app_name=None, namespace=None, **kwargs)

Bases: superdjango.views.viewsets.ViewSet

This utility class dynamically brings the various account views together.

# main/urls.py
from accounts.views import AccountsViewSet

accounts = AccountsViewSet(passwords=True, profiles=True)
auth = AccountsViewSet(auth=True)

urlpatterns = [
    # ...
    url(r'^accounts/', include(accounts.urls)),
    url(r'', include(auth.urls)),
    # ...
]

__init__(app_name=None, namespace=None, **kwargs)

Initialize the view set.

Parameters

• app_name (str) – The app name.

• namespace (str) – The namespace in which the app will operate.

Remaining kwargs may include a true/false value to enable or disable the URLs for a specific accounts app. No apps are enabled by default, which will produce no URLs. The valid keywords are:

• auth

• badges

• impersonation

• invitations

• locked

• multisso

• passwords

• profiles

• registrations

• sso

get_views()

Get the views enabled for this instance of the viewset.

Return type

list

Embeds

An app for embedding media in a page.

Component Reference: Embeds

library

class superdjango.contrib.embeds.library.BaseEmbedFinder(providers=None, response_format='json')

Bases: object

Base class for embed finders.

__init__(providers=None, response_format='json')

Initialize the embed.

Parameters

• providers – A list of providers to be used for identifying the embedded URL. Defaults to ALL_PROVIDERS.

• providers – list

• response_format (str) – The response format from the provider.

get(url, cache_enabled=True, **options)

Get the embed object.

Parameters

• url (str) – The URL to be embedded.

• cache_enabled (bool) – Draw from cache, if available.

• options (dict) – The options to be passed to the provider. For example, height or width.

Return type

Embed

Raises

EmbedNotFound

load()

Load providers, parsing endpoints and URLs.

Return type

bool

class superdjango.contrib.embeds.library.Embed(url, **kwargs)

Bases: object

Collect and deliver embedded output.

__init__(url, **kwargs)

Initialize the embed.

Parameters

• url (str) – The original URL.

• kwargs – The attributes of the embed. These become available as embed.<attribute_name>.

classmethod from_cache(path, url)

Get an embed from a cache file.

Parameters

• path (str) – The path to the cache file.

• url (str) – The original URL.

Return type

Embed

Warning

The path is not checked before attempting to read the file.

render()

Get the HTML for the embed.

Return type

str

write(path)

Save the embed to a cache file.

Parameters

path (str) – The path to the cache file.

Warning

The path is not checked before attempting to write the file.

class superdjango.contrib.embeds.library.OEmbedFinder(providers=None, response_format='json')

Bases: superdjango.contrib.embeds.library.BaseEmbedFinder

Find and load an embed based on the URL of the embedded content.

get(url, cache_enabled=True, **options)

Get an embed using oembed.

Parameters

• url (str) – The URL to be embedded.

• cache_enabled (bool) – Draw from cache, if available.

• options (dict) – Options to be passed to the provider.

get_from_cache(url)

Get the embed from cache rather than calling the provider.

Parameters

url (str) – The URL to be embedded.

Return type

Embed | None

Error Capture

Error (exception) capture and disposition.

Component Reference: Error Capture

backends

class superdjango.contrib.errors.backends.Bitbucket

Bases: superdjango.contrib.errors.backends.base.ErrorHandler

__init__()

Check for presence of bitbucket-python.

handle(report)

Post an error to Bitbucket issues.

class superdjango.contrib.errors.backends.CSV

Bases: superdjango.contrib.errors.backends.base.ErrorHandler

Write errors to a CSV file.

handle(report)

Write meta data to a CSV file and traceback to text file.

class superdjango.contrib.errors.backends.Email

Bases: superdjango.contrib.errors.backends.base.ErrorHandler

Send email regarding an error.

handle(report)

Send email to addresses defined in SUPERDJANGO_ERROR_CAPTURE_EMAILS.

class superdjango.contrib.errors.backends.ErrorHandler

Bases: object

Base class for creating an error handler.

__init__()

Initialize the context and check required settings.

handle(report)

Provide additional handling of the exception.

Parameters

report (django.views.debug.ExceptionReporter) – An exception reporter instance for the current exception(s).

Return type

dict | HttpResponse | None

traceback = <module 'traceback' from '/usr/local/Cellar/python@3.8/3.8.3_2/Frameworks/Python.framework/Versions/3.8/lib/python3.8/traceback.py'>

class superdjango.contrib.errors.backends.GitHub

Bases: superdjango.contrib.errors.backends.base.ErrorHandler

__init__()

Check for presence of PyGithub.

handle(report)

Post an error to GitHub issues.

class superdjango.contrib.errors.backends.Model

Bases: superdjango.contrib.errors.backends.base.ErrorHandler

Write errors to the database.

handle(report)

Create an error record.

middleware

class superdjango.contrib.errors.middleware.ErrorCaptureMiddleware(get_response)

Bases: object

Middleware for capturing exceptions.

__init__(get_response)

Initialize self. See help(type(self)) for accurate signature.

capture_exception(request, exception)

Runs the exception capture process.

Parameters

• request – The current HTTP request.

• exception – The exception being raised.

Return type

BaseType[HttpResponse]

process_exception(request, exception)

Process the exception.

traceback = <module 'traceback' from '/usr/local/Cellar/python@3.8/3.8.3_2/Frameworks/Python.framework/Versions/3.8/lib/python3.8/traceback.py'>

models

class superdjango.contrib.errors.models.ErrorModel(*args, **kwargs)

Bases: django.db.models.base.Model

Captures exception data to the database.

Parameters

• added_dt (DateTimeField) – Date and time the record was created.

• identifier (UUIDField) – A unique identifier.

• line (PositiveIntegerField) – The line number where the error occurred.

• name (CharField) – The name (exception type) of the error.

• path (CharField) – The path where the error occurred.

• traceback (TextField) – The traceback of the error.

get_display_name()

Get the display name for the error.

Return type

str

classmethod log(report)

Create a new error record.

Parameters

report (django.views.debug.ExceptionReporter) – An exception reporter instance for the current exception(s).

Returns

The error record instance.

utils

class superdjango.contrib.errors.utils.CSVDatabase(path)

Bases: superdjango.utils.library.File

The database for CSV error capture.

__init__(path)

Initialize the database.

Parameters

path (str) – The path to the CSV file.

fetch(identifier)

Get the error instance.

Parameters

identifier (str) – The unique identifier of the error.

Return type

CSVError | None

load()

Load the database.

Return type

bool

class superdjango.contrib.errors.utils.CSVError(**kwargs)

Bases: object

An individual error captured and stored in the CSV database.

__init__(**kwargs)

Initialize self. See help(type(self)) for accurate signature.

property file_name

Get the file name where the error occurred.

Return type

str

views

class superdjango.contrib.errors.views.CSVErrorDetail(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.templates.TemplateView

Load detail from an error collected by the CSV backend.

get_context_data(**kwargs)

Uses keyword arguments as the base context and adds the current view instance as view.

Return type

dict

The following variables are added to the context:

• active_page: The identifier for the active menu item.

• active_subpage: The identifier for the active sub-menu item.

• base_template: The template to extend, i.e. {% extends base_template %}.

• subtitle: The subtitle of the page.

• title: The title of the page.

• view: The current view instance.

• view_css: A Style instance.

• view_js: A JavaScript instance.

class superdjango.contrib.errors.views.CSVErrorList(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.templates.TemplateView

Load errors collected by the CSV backend.

get_context_data(**kwargs)

Uses keyword arguments as the base context and adds the current view instance as view.

Return type

dict

The following variables are added to the context:

• active_page: The identifier for the active menu item.

• active_subpage: The identifier for the active sub-menu item.

• base_template: The template to extend, i.e. {% extends base_template %}.

• subtitle: The subtitle of the page.

• title: The title of the page.

• view: The current view instance.

• view_css: A Style instance.

• view_js: A JavaScript instance.

class superdjango.contrib.errors.views.CSVErrorViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

Collects views for displaying errors logged to CSV.

class superdjango.contrib.errors.views.ModelErrorDetail(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.crud.DetailView

Load detail from an error collected by the Model backend.

classmethod get_model()

Override to provide developer-defined model.

class superdjango.contrib.errors.views.ModelErrorList(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.crud.ListView

Load errors collected by the Model backend.

classmethod get_model()

Override to provide developer-defined model.

class superdjango.contrib.errors.views.ModelErrorViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ModelViewSet

Collects views for displaying errors logged to the database.

History

An app for tracking the audit history of records in the database.

Component Reference: History

admin

class superdjango.contrib.history.admin.HistoryAdmin(model, admin_site)

Bases: superdjango.db.history.admin.BaseHistoryModelAdmin

get_fields(request, obj=None)

Hook for specifying fields.

models

class superdjango.contrib.history.models.History(*args, **kwargs)

Bases: superdjango.db.history.models.HistoryModel

An entry in the record history timeline.

Parameters

• id (AutoField) – Id

• absolute_url (CharField) – The URL of the model instance.

• added_dt (DateTimeField) – Date and time the action was taken.

• content_type_id (ForeignKey) – The internal content type of the object.

• object_id (CharField) – The object (record) ID.

• object_label (CharField) – The string representation of the object, i.e. it’s title, label, etc.

• user_id (ForeignKey) – The user that performed the action.

• user_name (CharField) – The name of the user that performed the action.

• verb (CharField) – The verb (action) taken on a record.

• verb_display (CharField) – The display value of the verb.

• verbose_name (CharField) – The verbose name of the model.

• field_changes (TextField) – Fields that changed as part of the history.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

classmethod log_field_changes(instance, verb, fields=None)

Log changes to fields to the field_changes field of the history record.

ui

class superdjango.contrib.history.ui.HistoryUI(site=None)

Bases: superdjango.ui.options.interfaces.ModelUI

Provide a UI for history entry.

check_permission(request, verb, field=None, record=None)

Only super users have delete access. All others are checked only for detail and list permissions.

Internationalization

Tools for assisting with internationalizing a site or application.

Component Reference: Internationalization

Abstract

Tools and resources for assisting with internationalizing a site or application.

Note

The i18n suite does not provide concrete models.

Form fields are provided as an alternative to model fields. In general, we feel these should be preferred because:

1. Form fields (and especially choices) may be customized at run time.

2. Choices may change with some regularity, which may generate unpredictable migrations.

See also https://docs.djangoproject.com/en/stable/topics/i18n/

And https://www.w3.org/International/questions/qa-i18n

Countries

Choices, form fields, and other resources for managing country data.

Component Reference: Countries

choices

ALL_COUNTRY_CHOICES: A full list of all country codes and labels in a flat choices format.

REGION_COUNTRY_CHOICES: Country choices organized by region. Format includes regions (option group) and country choices.

SUB_REGION_COUNTRY_CHOICES: Country choices organized by sub-region. Format includes sub-regions (option group) and country choices.

AFRICA_COUNTRY_CHOICES: Country choices for the Africa region.

AMERICAS_COUNTRY_CHOICES: Country choices for the Americas region.

ASIA_COUNTRY_CHOICES: Country choices for the Asian region.

EUROPE_COUNTRY_CHOICES: Country choices for the European region.

OCEANIA_COUNTRY_CHOICES: Country choices for the Oceania region.

descriptors

These descriptors are generic classes that pertain to various aspects of country data. The class names match the section names of the INI file used to store the data.

class superdjango.contrib.i18n.countries.descriptors.Addressing(code, **kwargs)

Bases: object

A descriptor for country address specifications.

__init__(code, **kwargs)

Initialize and address specification.

Parameters

• code (str) – The two-character ISO-3166 country code.

• city_field_name – The name of the form or database field.

• city_label – The name equivalent of cities for the country. For example, locality.

• city_required – Indicates that the city field is typically required for an address to be valid.

• fields – A dictionary of field names and field widgets or field clasess to use for forms.

• postal_code_field_name – The name of the form or database field.

• postal_code_label – The name equivalent of postal code for the country. For example, ZIP code.

• postal_code_required – Indicates that the postal code field is required for an address to be valid.

• regions – A list of regions that may be used as choices. See has_regions.

• state_field_name – The name of the form or database field.

• state_label – The name equivalent of states for the country. For example, province.

• state_required – Indicates that the state field is typically required for an address to be valid.

param states: A list of states that may be used as choices. See has_states.

property has_regions

Indicates the country has administrative divisions apart from states.

Return type

bool

property has_states

Indicates the country has administrative or legal divisions such as states, provinces, etc.

Return type

bool

class superdjango.contrib.i18n.countries.descriptors.Codes(fips=None, iso2=None, iso3=None, ison=None, phone=None, stanag=None, tld=None)

Bases: object

A collection of country codes.

__init__(fips=None, iso2=None, iso3=None, ison=None, phone=None, stanag=None, tld=None)

Keyword arguments are the various possible codes.

Parameters

• fips – The FIPs code.

• iso2 – The two-character ISO-3166 code.

• iso3 – The three-character ISO-3166 code.

• ison – The ISON code.

• phone – The country code for phone calls.

• stanag – The STANAG code.

• tld – The top-level domain code.

class superdjango.contrib.i18n.countries.descriptors.Country(code, **kwargs)

Bases: object

A country descriptor. This descriptor incorporates various attributes and sub-objects to represent a country.

Example:

from superdjango.contrib.i18n.countries import country_factory

country = country_factory("UY")
print(country.name)

Attributes

Some, but rarely all, of the following properties are available:

• capital: The capital city of the country.

• comment: Any comment regarding the country data.

• code: The two-character ISO 3166 code.

• name: The country name.

Objects

More complex objects are used to represent additional data.

• address is an instance of Address.

• codes is an instance of Codes.

• currency is an instance of Currency.

• languages a list of Language` instances.

• wiki is an instance of Wiki.

Flags

The flag and icon properties may be used to display the country’s flag. For convenience, CSS and images have been bundled from: https://github.com/lipis/flag-icon-css

__init__(code, **kwargs)

Initialize a country.

Parameters

code (str) – The two-character ISO-3166 code of the country.

property flag

Get the URL for the country’s flag image.

Return type

str

This is intended for use with the static template tag:

{% static country.flag %}

property icon

Get the flag as an HTML icon.

Return type

str

Note

This requires that you include i18n/flags/css/flag-icon.css (or flag-icon.min.css) in your template.

class superdjango.contrib.i18n.countries.descriptors.Geography(code, name)

Bases: object

A descriptor for regions, sub-regions, or intermediate regions into which countries are organized.

Tip

Do not confuse the terminology with regions in address specification.

__init__(code, name)

Initialize self. See help(type(self)) for accurate signature.

class superdjango.contrib.i18n.countries.descriptors.Wiki(**kwargs)

Bases: object

A descriptor for country Wiki URLs.

Attributes

A wiki instance may include 2 properties; capital is URL of the country’s capital, while country is the URL of the country page.

__init__(**kwargs)

Initialize a Wikipedia descriptor.

Parameters

• capital (str) – The capital URL of the country.

• country (str) – The country URL.

factories

superdjango.contrib.i18n.countries.factories.country_factory(code, lang='en_US')

Load a country descriptor.

Parameters

• code (str) – The two-character ISO-3166 code of the country.

• lang (str) – The language to use when loading country data.

Return type

Country | None

Raise

ValueError

Raises

ValueError if the corresponding INI file does not have a [country] section. This should never happen, but is possible if malformed data is inadvertently introduced.

forms

class superdjango.contrib.i18n.countries.forms.CountryField(**kwargs)

Bases: django.forms.fields.ChoiceField

Provide country choices.

__init__(**kwargs)

choices defaults to SUB_REGION_COUNTRY_CHOICES, and initial defaults to SUPERDJANGO_I18N_DEFAULT_COUNTRY_CODE if defined in settings.

Currencies

Choices, form fields, and other resources for managing currency data.

Component Reference: Currencies

choices

ALL_CURRENCY_CHOICES: A big honking list of all currencies.

COMMON_CURRENCY_CHOICES: A much short list of arguably common currencies.

descriptors

class superdjango.contrib.i18n.currencies.descriptors.Currency(code, name)

Bases: object

A descriptor for currency specification.

__init__(code, name)

Initialize the descriptor.

Parameters

• code (str) – The currency code.

• name (str) – The currency name.

forms

class superdjango.contrib.i18n.currencies.forms.CurrencyField(**kwargs)

Bases: django.forms.fields.ChoiceField

Provide country choices.

__init__(**kwargs)

choices defaults to COMMON_CURRENCY_CHOICES, and initial defaults to SUPERDJANGO_I18N_DEFAULT_CURRENCY_CODE if defined in settings.

Languages

Choices, constants, form fields, and other resources for managing language data.

Component Reference: Languages

choices

ALL_LANGUAGE_CHOICES codes are provided as the (IANA) choice value, and the label is a unicode string with the option for lazy translation.

COMMON_LANGUAGE_CHOICES are provided as an alternative to the massive list of languages and were (mostly) selected based on the number of people that speak the language.

constants

LANGUAGES is a dictionary with the tag (code) and localized name. Tags come from the IANA registry.

MAX_CHOICE_LENGTH is provided as an alternative to a bare/magic number.

descriptors

class superdjango.contrib.i18n.languages.descriptors.Language(code, country=None, label=None)

Bases: object

A language descriptor.

__init__(code, country=None, label=None)

Initialize self. See help(type(self)) for accurate signature.

get_localized_name()

Get the localized (unicode) name of the language.

Return type

str | unicode

Note

If the tag is not found, the language label is returned.

property is_valid

Indicates whether the language code is valid.

Return type

bool

property label

Get the language label.

Return type

str

property localized_name

Alias for get_localized_name().

forms

class superdjango.contrib.i18n.languages.forms.LanguageChoiceField(**kwargs)

Bases: django.forms.fields.ChoiceField

A field that presents language choices.

By default, COMMON_LANGUAGE_CHOICES are used, so passing more or less choices may be desirable instead.

__init__(**kwargs)

Initialize self. See help(type(self)) for accurate signature.

Time Zones

Choices, constants, form fields, and other resources for managing timezones.

Component Reference: Time Zones

choices

Regional Choices

AFRICAN_TIMEZONE_CHOICES: Timezone choices for Africa.

ANTARCTIC_TIMEZONE_CHOICES: Timezone choices for Antarctica.

ASIAN_TIMEZONE_CHOICES: Timezone choices for Asia.

ATLANTIC_TIMEZONE_CHOICES: Timezone choices for the Atlantic.

AUSTRALIAN_TIMEZONE_CHOICES: Timezone choices for the Australia.

CANADIAN_TIMEZONE_CHOICES: Timezone choices for the Canada.

CENTRAL_AMERICAN_TIMEZONE_CHOICES: Timezone choices for the Central America. Includes the Caribbean.

EUROPEAN_TIMEZONE_CHOICES: Timezone choices for Europe.

MEXICAN_TIMEZONE_CHOICES: Timezone choices for Mexico.

MIDDLE_EASTERN_TIMEZONE_CHOICES: Timezone choices for the Middle East.

PACIFIC_TIMEZONE_CHOICES: Timezone choices for the Pacific.

SOUTH_AMERICAN_TIMEZONE_CHOICES: Timezone choices for South America.

US_TIMEZONE_CHOICES: Timezone choices for the United States.

Choice Collections

ALL_TIMEZONE_CHOICES: The big, honking list of all timezone choices.

COMMON_TIMEZONE_CHOICES: Common timezone choices, which may or may not be considered common depending on where you’re from. Also includes UTC.

NORTH_AMERICAN_TIMEZONE_CHOICES: North American timezone choices includes Canada, Mexico, and the United States.

constants

Regional Lists

AFRICAN_TIMEZONES: Timezones for Africa.

ANTARCTIC_TIMEZONES: Timezones for Antarctica.

ASIAN_TIMEZONES: Timezones for Asia.

ATLANTIC_TIMEZONES: Timezones for the Atlantic.

AUSTRALIAN_TIMEZONES: Timezones for the Australia.

CANADIAN_TIMEZONES: Timezones for the Canada.

CENTRAL_AMERICAN_TIMEZONES: Timezones for the Central America. Includes the Caribbean.

EUROPEAN_TIMEZONES: Timezones for Europe.

MEXICAN_TIMEZONES: Timezones for Mexico.

MIDDLE_EASTERN_TIMEZONES: Timezones for the Middle East.

PACIFIC_TIMEZONES: Timezones for the Pacific.

SOUTH_AMERICAN_TIMEZONES: Timezones for South America.

US_TIMEZONES: Timezones for the United States.

Timezone Collections

ALL_TIMEZONES: The big, honking list of all timezones.

COMMON_TIMEZONES: Common timezones, which may or may not be considered common depending on where you’re from. Also includes UTC.

NORTH_AMERICAN_TIMEZONES: North American timezones includes Canada, Mexico, and the United States.

descriptors

class superdjango.contrib.i18n.timezones.descriptors.TimeZone(code, label=None)

Bases: object

Represents a timezone.

__init__(code, label=None)

Initialize a timezone instance.

Parameters

• code (str) – The pytz code for the timezone.

• label (str) – The label for the timezone.

as_pytz()

Get the timezone from pytz.

Return type

datetime.tzinfo

property is_valid

Indicates whether the timezone is valid.

Return type

bool

property label

Get the timezone label.

Return type

str

forms

class superdjango.contrib.i18n.timezones.forms.TimeZoneField(**kwargs)

Bases: django.forms.fields.ChoiceField

A form field which accepts valid time zone choices.

__init__(**kwargs)

choices defaults to COMMON_TIMEZONE_CHOICES.

class superdjango.contrib.i18n.timezones.forms.TimeZoneSelectionForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None)

Bases: django.forms.forms.Form

Allows a user to select his or her timezone preference.

class superdjango.contrib.i18n.timezones.forms.TimeZoneSettingsForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, instance=None, use_required_attribute=None, renderer=None)

Bases: django.forms.models.ModelForm

Presents timezone settings with the default and default choices.

middleware

class superdjango.contrib.i18n.timezones.middleware.TimeZoneMiddleware(get_response)

Bases: object

Set the current time zone; either that of the user or the system default.

This is pretty much straight from the example found in Django documentation, but with new-style middleware.

See: https://docs.djangoproject.com/en/stable/topics/i18n/timezones/#selecting-the-current-time-zone

__init__(get_response)

Initialize self. See help(type(self)) for accurate signature.

models

class superdjango.contrib.i18n.timezones.models.TimeZoneSettingsModel(*args, **kwargs)

Bases: solo.models.SingletonModel

Manage the availability of time zones.

Parameters

• default_timezone (CharField) – The default time zone.

• african_enabled (BooleanField) – Indicates African time zones are enabled.

• asian_enabled (BooleanField) – Indicates Asian time zones are enabled.

• australian_enabled (BooleanField) – Indicates Australian time zones are enabled.

• canadian_enabled (BooleanField) – Indicates Canadian time zones are enabled.

• central_american_enabled (BooleanField) – Indicates Central American time zones are enabled. Includes the Caribbean.

• european_enabled (BooleanField) – Indicates European time zones are enabled.

• mexican_enabled (BooleanField) – Indicates U.S. time zones are enabled.

• middle_eastern_enabled (BooleanField) – Indicates Middle Eastern time zones are enabled.

• south_american_enabled (BooleanField) – Indicates South American time zones are enabled.

• us_enabled (BooleanField) – Indicates U.S. time zones are enabled.

get_timezone_choices()

Get the collective time zone choices available to users.

Return type

list

utils

superdjango.contrib.i18n.timezones.utils.get_timezone_label(code)

Get the label for the timezone.

Parameters

code (str) – The pytz timezone code.

Return type

str

Raise

UnknownTimeZoneError

superdjango.contrib.i18n.timezones.utils.is_pytz_instance(value)

Determines whether the given value is a BaseTzInfo instance.

Return type

bool

superdjango.contrib.i18n.timezones.utils.is_valid_timezone(code)

Determines whether the given code is a valid pytz timezone code.

Parameters

code (str) – The pytz timezone code.

Return type

bool

views

superdjango.contrib.i18n.timezones.views.set_my_timezone(request)

Allows the current user to set his or her timezone.

Notifications

Facilitates user notifications within a project, optionally sending email and SMS.

Component Reference: Notifications

admin

class superdjango.contrib.notifications.admin.CategoryAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Django admin for notification categories.

class superdjango.contrib.notifications.admin.NotificationAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Django admin for notifications.

class superdjango.contrib.notifications.admin.NotificationUserAdmin(model, admin_site)

Bases: django.contrib.admin.options.ModelAdmin

Django admin for user notifications log.

constants

superdjango.contrib.notifications.constants.DEFAULT_ICONS = {10: 'fas fa-bug', 20: 'fas fa-info-circle', 25: 'fas fa-check-circle', 30: 'fas fa-exclamation-triangle', 40: 'fas fa-exclamation-circle'}

Map levels to Font Awesome icons.

class superdjango.contrib.notifications.constants.LEVEL

Bases: object

A notification level (using levels from django.contrib.messages.constants).

class superdjango.contrib.notifications.constants.STAGE

Bases: object

The stage of a notification.

models

class superdjango.contrib.notifications.models.Category(*args, **kwargs)

Bases: superdjango.db.lookups.models.StringLookupModel

Notification categories.

Parameters

• id (AutoField) – Id

• abbr (CharField) – Enter the common abbreviation for the entry, if any.

• description (TextField) – Brief description of the entry.

• is_enabled (BooleanField) – Indicates the lookup is enabled for use.

• label (CharField) – Official name or title for the entry.

• value (CharField) – The value of the lookup.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

class superdjango.contrib.notifications.models.Notification(*args, **kwargs)

Bases: django.db.models.base.Model

A notification sent to a user.

Parameters

• id (AutoField) – Id

• action_text (CharField) – The text to display for the action. Defaults to “More” in templates.

• action_url (CharField) – The URL to which users should be directed to take action or get more information.

• added_dt (DateTimeField) – Date and time the notification was added.

• category_id (ForeignKey) – The category of the message.

• body (TextField) – The body of the message.

• body_sms (TextField) – The SMS/text body of the message.

• email_enabled (BooleanField) – Indicates the message should be sent via email.

• has_been_sent (BooleanField) – Indicates the notification has been sent.

• html_enabled (BooleanField) – Indicates HTML email output should be supported.

• icon_override (CharField) – Override the default icon.

• is_mandatory (BooleanField) – Indicates the notification should be sent regardless of user preferences.

• is_promoted (BooleanField) – Indicates the notification should be promoted to prominence.

• level (PositiveSmallIntegerField) – The level of the notification.

• sent_dt (DateTimeField) – Date and time the notification was sent.

• sms_enabled (BooleanField) – Indicates the message should be sent via SMS/text.

• stage (PositiveSmallIntegerField) – The current stage of the notification.

• subject (CharField) – The subject line of the message.

• users (ManyToManyField) – The users to which the notification is sent.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

classmethod create_for(body, subject, users, action_text=None, action_url=None, body_sms=None, category=None, email_enabled=False, html_enabled=False, icon_override=None, is_mandatory=False, is_promoted=False, level=20, sms_enabled=False)

Create a notification for the given users.

Parameters

• body (str) – Required. The body of the message.

• subject (str) – Required. The subject line of the message.

• users – An iterable of users to which the notification should be sent.

• action_text (str) – The action text to display for the URL. Defaults to “More” in templates.

• action_url (str) – Optional. The action URL.

• body_sms (str) – Optional. The SMS/text version of the message.

• category (str | Category) – The message category.

• email_enabled (bool) – Indicates email should be sent. Requires additional setup.

• html_enabled (bool) – Indicates the body of the message is HTML.

• icon_override (str) – Overrides the default icon.

• is_mandatory (bool) – Indicates the message should be sent regardless of user preferences.

• is_promoted (bool) – Indicates the message should be displayed with prominence.

• level (int) – The level of the message.

• sms_enabled (bool) – Indicates email should be sent. Requires additional setup.

Return type

Notification

Warning

This creates a notification that is immediately queued for delivery.

get_icon()

Get the Font Awesome icon associated with the level.

Return type

str

property icon

Alias for get_icon().

mark_sent(commit=True)

Mark the notification as sent.

Parameters

commit (bool) – Save after updating the fields.

class superdjango.contrib.notifications.models.NotificationUser(*args, **kwargs)

Bases: django.db.models.base.Model

Track the users that have seen a notification.

Parameters

• id (AutoField) – Id

• has_been_viewed (BooleanField) – Indicates the notification has been viewed.

• notification_id (ForeignKey) – The notification being tracked.

• sent_email (NullBooleanField) – Indicates whether an email was sent for this notification.

• sent_sms (NullBooleanField) – Indicates whether a SMS/text was sent for this notification.

• user_id (ForeignKey) – The user to which the notification is sent.

• viewed_dt (DateTimeField) – Date and time the notification was viewed.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

property action_url

Alias on notification.

property added_dt

Alias on notification.

property body

Alias on notification.

property body_sms

Alias on notification.

property email_enabled

Alias on notification.

get_level_display()

Alias on notification.

property has_been_sent

Alias on notification.

property icon

Alias on notification.

property is_mandatory

Alias on notification.

property is_promoted

Alias on notification.

property level

Alias on notification.

mark_unviewed(commit=True)

Mark the record as “un-viewed”, removing the last viewed data.

Parameters

commit (bool) – Indicates the record should be saved after updating the field.

mark_viewed(commit=True)

Mark the record as viewed.

Parameters

commit (bool) – Indicates the record should be saved after updating the field.

property sent_dt

Alias on notification.

property sms_enabled

Alias on notification.

property stage

Alias on notification.

property subject

Alias on notification.

class superdjango.contrib.notifications.models.UserPreferences(*args, **kwargs)

Bases: django.db.models.base.Model

User notification preferences.

Parameters

• id (AutoField) – Id

• email_enabled (BooleanField) – Indicates email notifications are enabled. Some mandatory messages may be sent even when disabled.

• level (PositiveSmallIntegerField) – The minimum level of the notifications to receive.

• mobile_number (CharField) – The mobile number at which SMS/text notifications may be received. Note: Mobile charges may apply.

• sms_enabled (BooleanField) – Indicates messages may be sent via SMS/text.

• user_id (OneToOneField) – The user to which the preferences belong.

• categories (ManyToManyField) – The category or categories of notifications to be received.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

shortcuts

class superdjango.contrib.notifications.shortcuts.Message(notification, user, preferences=None)

Bases: object

Represents a single email and/or SMS message to a user.

__init__(notification, user, preferences=None)

Initialize a message.

Parameters

• notification (superdjango.contrib.notifications.models.Notification) – The notification instance.

• user (AUTH_USER_MODEL) – The user instance.

• preferences (superdjango.contrib.notifications.models.UserPreference) – The user preference instance.

email()

Send a notification via email.

Return type

bool

Returns

True if the email was sent.

sms()

Send a notification via SMS/text.

Return type

bool

Returns

True if the SMS was sent.

superdjango.contrib.notifications.shortcuts.get_promoted_notification(user)

Get the (first) promoted notification for the given user.

Parameters

user (AUTH_USER_MODEL) – The user instance to be checked.

Return type

NotificationUser | None

superdjango.contrib.notifications.shortcuts.get_sms_callback(raise_exception=True)

Get the callback function used to send SMS/text messages.

The callback is defined using SUPERDJANGO_NOTIFICATIONS_SMS_CALLBACK which is the dotted path to a callable that accepts a body, mobile number, and optionally a from number.

def send_sms(body, number, from_number=None):
    # ...

superdjango.contrib.notifications.shortcuts.get_unread_notification_count(user)

Get the unread notification count for a user.

Parameters

user (AUTH_USER_MODEL) – The user instance to be checked.

Return type

int

superdjango.contrib.notifications.shortcuts.get_unread_notifications(user)

Get the unread notifications for a user.

Parameters

user (AUTH_USER_MODEL) – The user instance to be checked.

Return type

QuerySet

superdjango.contrib.notifications.shortcuts.has_unread_notifications(user)

Indicates whether a given user has unread notifications.

Parameters

user (AUTH_USER_MODEL) – The user instance to be checked.

Return type

bool

superdjango.contrib.notifications.shortcuts.notify(body, subject, action_url=None, email_enabled=False, icon_override=None, level=20, users=None)

Issue a notification.

Parameters

• body (str) – The body of the notification.

• subject (str) – The subject of the notification.

• action_url (str) – The URL to which the user is directed.

• email_enabled (bool) – Indicates the notification should be sent via email. Otherwise, it is only an in-app notification.

• icon_override (str) – The icon to use for the notification. Overrides the default.

• level (int) – The notification level.

• users (list[AUTH_USER_MODEL]) – The users to which the notification should be sent. It omitted, all active users are notified.

Return type

Notification

ui

class superdjango.contrib.notifications.ui.CategoryUI(site=None)

Bases: superdjango.ui.options.interfaces.ModelUI

A user interface for notification category lookups.

model

alias of superdjango.contrib.notifications.models.Category

class superdjango.contrib.notifications.ui.NotificationUI(site=None)

Bases: superdjango.ui.options.interfaces.ModelUI

A user interface for user notifications.

model

alias of superdjango.contrib.notifications.models.Notification

class superdjango.contrib.notifications.ui.NotificationUserUI(site=None)

Bases: superdjango.ui.options.interfaces.ModelUI

User interface for the user notification log.

model

alias of superdjango.contrib.notifications.models.NotificationUser

class superdjango.contrib.notifications.ui.NotificationsMenu(site=None)

Bases: superdjango.ui.options.menus.Menu

views

class superdjango.contrib.notifications.views.AjaxMarkNotificationRead(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.ajax.mixins.JSONMixin, django.views.generic.base.View

Mark a notification as viewed.

get(request, *args, **kwargs)

Process the request.

class superdjango.contrib.notifications.views.AjaxNotificationsViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

Collect AJAX notification views.

class superdjango.contrib.notifications.views.AjaxUnreadNotifications(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.ajax.mixins.JSONMixin, django.views.generic.base.View

Get unread notifications in real time.

get(request, *args, **kwargs)

Process the request.

class superdjango.contrib.notifications.views.NotificationDetail(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.crud.DetailView

Display the detail of a notification.

get_breadcrumbs()

Get breadcrumbs for notification detail

get_context_data(**kwargs)

Mark the notification as viewed.

get_queryset()

Also filter the object for the current user.

model

alias of superdjango.contrib.notifications.models.NotificationUser

class superdjango.contrib.notifications.views.NotificationList(**kwargs)

Bases: superdjango.views.access.LoginRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.crud.ListView

Display a list of notifications.

get_queryset()

Also filter the objects for the current user.

model

alias of superdjango.contrib.notifications.models.NotificationUser

class superdjango.contrib.notifications.views.NotificationsViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ModelViewSet

Collect standard notification views for end-users.

Releases

Provides support for managing project releases.

Component Reference: Releases

constants

superdjango.contrib.releases.constants.RELEASE_PATH = '/Users/shawn/Work/superdjango4/tests/example_project/source/../deploy/releases'

The path to the releases directory is where individual release directories are stored.

superdjango.contrib.releases.constants.VERSION_PATH = '/Users/shawn/Work/superdjango4/tests/example_project/source/../VERSION.txt'

The path to the version file.

releases

class superdjango.contrib.releases.library.releases.Release(identifier, content=None, date=None, description=None, scope=None)

Bases: object

Encapsulate release information.

__init__(identifier, content=None, date=None, description=None, scope=None)

Initialize self. See help(type(self)) for accurate signature.

to_html()

Export release content as HTML.

Return type

str

superdjango.contrib.releases.library.releases.factory(identifier, path=None)

Load a release.

Parameters

• identifier (str) – The release identifier (same as directory name).

• path (str) – The path to the releases directory.

Return type

Release | None

superdjango.contrib.releases.library.releases.get_releases(limit=10, path=None)

Load release data.

Parameters

• limit (int) – The total number of releases to return.

• path (str) – The path to the releases directory.

Return type

list[Release]

versions

This utility is based upon Semantic Versioning. By default it operates on VERSION.txt.

Calling the command with no arguments will simply print the current version.

class superdjango.contrib.releases.library.versions.Version(identifier)

Bases: object

Represents a version/release string.

__init__(identifier)

Initialize a version.

Parameters

identifier (str) – The version string in semver.org format.

bump(major=False, minor=False, patch=False, status=None, build=None)

Bump the version.

Parameters

• major (bool) – Indicates major version should be increased. Minor and patch are reset to 0.

• minor (bool) – Indicates minor version should be increased. Patch is reset to 0.

• patch – Indicates the patch level should be increased.

• status (str) – The value of the pre-release identifier.

• build (str) – The value of the build name.

Return type

str

Returns

The new version (striped).

superdjango.contrib.releases.library.versions.bump_version(current, major=False, minor=False, patch=False, status=None, build=None)

Bump the version.

Parameters

• current (str) – The current version.

• major (bool) – Indicates major version should be increased. Minor and patch are reset to 0.

• minor (bool) – Indicates minor version should be increased. Patch is reset to 0.

• patch – Indicates the patch level should be increased.

• status (str) – The value of the pre-release identifier.

• build (str) – The value of the build name.

Return type

str

Returns

The new version (striped).

superdjango.contrib.releases.library.versions.get_current_version(path=None)

Get the current version.

Parameters

path (str) – The path to the version file.

Return type

str

Returns

The current version. If the version path does not exist, this will be 0.1.0-d.

views

class superdjango.contrib.releases.views.LoginMayBeRequiredMixin

Bases: superdjango.views.access.AccessMixin

An authenticated user may or may not be required.

class superdjango.contrib.releases.views.ReleaseDetail(**kwargs)

Bases: superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.contrib.releases.views.LoginMayBeRequiredMixin, superdjango.views.templates.TemplateView

Display information regarding a specific release.

get_base_template()

Use support base if installed.

get_breadcrumbs()

Get the breadcrumbs for the view.

Return type

Breadcrumbs

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.releases.views.ReleaseIndex(**kwargs)

Bases: superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.contrib.releases.views.LoginMayBeRequiredMixin, superdjango.views.templates.TemplateView

Display a list of release information.

get_base_template()

Use support base if installed.

get_breadcrumbs()

Get the breadcrumbs for the view.

Return type

Breadcrumbs

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.releases.views.ReleasesViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

Scheduler

Provides support for scheduling jobs from the command line.

Component Reference: Scheduler

constants

superdjango.contrib.scheduler.constants.DEFAULT_INTERVAL = 1

The default interval for jobs.

class superdjango.contrib.scheduler.constants.FREQUENCIES

Bases: object

Pre-defined job frequencies.

superdjango.contrib.scheduler.constants.FREQUENCY_CHOICES = ('second', 'seconds', 'minute', 'minutes', 'hour', 'hours', 'day', 'days', 'week', 'weeks', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday')

A list of all available frequencies for the command line.

class superdjango.contrib.scheduler.constants.STATUS

Bases: object

The execution status of scheduled job.

decorators

superdjango.contrib.scheduler.decorators.catch_exceptions(cancel_on_failure=False)

A decorator to be applied to a scheduled job callback. Straight from the python-schedule documentation.

Parameters

cancel_on_failure (bool) – Indicates the job should be canceled when an exception is raised.

from superdjango.contrib.scheduler.decorators import catch_exceptions

@catch_exceptions(cancel_on_failure=True)
def bad_task():
    return 1 / 0

schedule.every(5).minutes.do(bad_task)

interfaces

class superdjango.contrib.scheduler.interfaces.Registry(label='global')

Bases: object

Register jobs to be executed on a schedule.

__init__(label='global')

Initialize self. See help(type(self)) for accurate signature.

get_jobs(app_name=None)

Get the jobs that have been registered.

Parameters

app_name (str) – Get the jobs only for the given app name.

Return type

list[superdjango.contrib.scheduler.library.Job]

register(app_name, callback, active=False, at=None, description=None, frequency=None, interval=None, label=None, **kwargs)

Register a job.

Parameters

• app_name (str) – The name of the app.

• callback – The callable to be executed.

• active (bool) – Indicates the job is to be executed.

• at (str) – The specific time at which job should run.

• description (str) – Optional, additional description of the job.

• frequency (str) – The frequency upon which the job runs.

• interval (int) – The interval upon which the job runs.

• label (str) – The label of the job. Defaults to the name of the callback.

kwargs are passed as parameters to the callback.

library

class superdjango.contrib.scheduler.library.Job(label, active=True, app_name=None, at=None, callback=None, description=None, frequency='minute', interval=1, pk=None, **kwargs)

Bases: object

A scheduled job.

__init__(label, active=True, app_name=None, at=None, callback=None, description=None, frequency='minute', interval=1, pk=None, **kwargs)

Initialize a job.

Parameters

• label (str) – The name or label for the job.

• active (bool) – Indicates the job is to be executed.

• app_name (str) – The app from which the job originates.

• at (str) – The specific time at which job should run.

• callback – The dotted path to the callback for job execution. May also be provided as a callable.

• description (str) – Optional, additional description of the job.

• frequency (str) – The frequency upon which the job runs.

• interval (int) – The interval upon which the job runs.

• pk (int) – The primary key of the job record associated with this job. Only used when auto-discovery is enabled.

kwargs are passed as parameters to the callback.

property every

Recombines interval and frequency.

Return type

str

get_callback()

Alias for _import_callback().

run()

Execute the job.

Return type

Result

to_ini()

Export the job to INI format.

Return type

str

to_markdown()

Export the job to Markdown format.

Return type

str

to_plain()

Export the job to plain text format.

Return type

str

to_rst()

Export the job to ReStructuredText format.

Return type

str

class superdjango.contrib.scheduler.library.Result(status, end_dt=None, label=None, message=None, output=None, start_dt=None)

Bases: object

The result of a scheduled job.

__init__(status, end_dt=None, label=None, message=None, output=None, start_dt=None)

Initialize a result.

Parameters

• status (str) – The status of the execution.

• end_dt (datetime) – The date and time the job completed. Defaults to now.

• label (str) – The job label.

• message (str) – The human-friendly message.

• output (str) – The output, if any, produced by the job.

• start_dt (datetime) – The date and time the job started. Defaults to now.

property elapsed_time

The amount of time that passed to execute the job.

Return type

timedelta

property failure

Indicates the job failed to properly execute.

Return type

bool

property success

Indicates the job was successfully executed.

Return type

bool

class superdjango.contrib.scheduler.library.Schedule(label=None)

Bases: object

A collection of scheduled jobs.

__init__(label=None)

Initialize self. See help(type(self)) for accurate signature.

to_ini()

Export all jobs to INI format.

Return type

str

to_markdown(tabular=False)

Export the schedule as Markdown.

Parameters

tabular (bool) – Indicates the expected output is in table form.

Return type

str

to_plain(tabular=False)

Export the schedule as plain text.

Parameters

tabular (bool) – Indicates the expected output is in table form.

Return type

str

to_rst(tabular=False)

Export the schedule as ReStructuredText.

Parameters

tabular (bool) – Indicates the expected output is in table form.

Return type

str

superdjango.contrib.scheduler.library.factory(path, label=None)

Initialize a schedule from the given path.

Parameters

• path (str) – The path to the scheduler.ini file.

• label (str) – The label for the schedule. Defaults to the path with separators changed to dashes.

models

class superdjango.contrib.scheduler.models.Activity(*args, **kwargs)

Bases: django.db.models.base.Model

The result of a scheduled job.

Parameters

• id (AutoField) – Id

• added_dt (DateTimeField) – Date and time the entry was recorded.

• cached_job_label (CharField) – The name or label of th job.

• cached_success (BooleanField) – Indicates success for failure.

• elapsed_time (DurationField) – The time that passed from start to finish of job execution.

• end_dt (DateTimeField) – Date and time the job finished.

• job_id (ForeignKey) – The job with which the activity is associated

• message (TextField) – The message from the activity that may be displayed to users.

• output (TextField) – The raw output of the command.

• start_dt (DateTimeField) – Date and time the job began.

• status (CharField) – The status of the activity.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

get_css_color()

Get the CSS color style bass on the activity status.

Return type

str

get_display_name()

Get a more verbose label for the activity.

Return type

str

get_icon()

Get the icon (style) based on the activity status.

Return type

str

classmethod log(job_id, result)

Log activity for a given job.

Parameters

• job_id (int) – The job ID (pk) of the job that was executed.

• result (superdjango.contrib.scheduler.library.Result) – The result of the job.

Return type

Activity

save(*args, **kwargs)

Send a message on critical status.

class superdjango.contrib.scheduler.models.Job(*args, **kwargs)

Bases: superdjango.db.audit.models.AddedByModel, superdjango.db.audit.models.ModifiedByModel

A job to be scheduled.

Parameters

• id (AutoField) – Id

• added_by_id (ForeignKey) – Added by

• added_dt (AutoNowAddDateTimeField) – Date and time the record was created.

• modified_by_id (ForeignKey) – Modified by

• modified_dt (AutoNowDateTimeField) – Date and time the record was last modified.

• app_name (CharField) – The app from which the job originates.

• at (TimeField) – The specific time at which the job will run.

• callback (CharField) – The callback that executes the job.

• description (TextField) – A brief description of the job.

• frequency (CharField) – The frequency of the job.

• interval (PositiveSmallIntegerField) – The interval upon which the job runs.

• is_active (BooleanField) – Indicates the job is enabled for execution.

• label (CharField) – The name or label of th job.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

property every

Recombines interval and frequency.

Return type

str

Support

Provides management support or help content from within a project.

Component Reference: Support

library

Re-usable resources for support content.

class superdjango.contrib.support.library.Area(name, **kwargs)

Bases: object

An overall area of content.

__init__(name, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

property articles

Alias for get_articles().

get_articles()

Get all articles for the area.

Return type

list[Article]

class superdjango.contrib.support.library.Article(content, path, content_type='article', **kwargs)

Bases: superdjango.utils.library.File

A support article.

__init__(content, path, content_type='article', **kwargs)

Initialize an article.

Parameters

• content (str) – The raw content of the article.

• path (str) – The path to the article file.

• content_type (str) – The content type of the article.

keyword arguments are available dynamically as attributes of the article.

property content

Get the Markdown content of the article.

Return type

str

property content_list

Get the content when it is a list of FAQ or Term instances.

Return type

list

get_word_count()

Get the total number of words.

Return type

int

property slug

Alias for name.

to_html(extensions=['extra'])

Export to HTML.

Parameters

extensions (list[str]) – A list of Markdown extensions to apply.

Return type

str

Returns

The content passed through mark_safe().

property url

Get the URL of the article.

Return type

str

class superdjango.contrib.support.library.Content(path)

Bases: object

The content database.

__init__(path)

Initialize the database.

Parameters

path (str) – The path to the database.

fetch(slug)

Get an object from the database.

Parameters

slug (str) – The slug of the object.

Returns

The object, if found. Otherwise, None.

get_content_files()

Get the content files acquired using load().

Return type

list

load()

Load all help content.

Return type

bool

class superdjango.contrib.support.library.FAQ(question, answer=None, area=None, category=None, sticky=False, tags=None)

Bases: object

A frequently asked question.

__init__(question, answer=None, area=None, category=None, sticky=False, tags=None)

Initialize the question.

Parameters

• question (str) – The question text.

• answer (str) – The answer text.

• area (str) – The area to which the FAQ is belongs.

• category (str) – The category into which FAQ is organized.

• sticky (bool) – Indicates the FAQ should appear at the top of lists.

• tags (str) – A comma separated list of tags used to classify the FAQ.

property content

Get the question and its answer. Complies with the overall API.

Return type

str

property path

Get the path to the FAQ file. Complies with the overall API.

Return type

str

property slug

Always returns faqs.

to_markdown()

Export the FAQ to Markdown.

Return type

str

class superdjango.contrib.support.library.Manifest(path)

Bases: superdjango.utils.library.File

The manifest controls what content is to be included in the database.

__init__(path)

Initialize the manifest.

Parameters

path (str) – The path to the manifest file.

load()

Load file paths from the manifest.

Return type

bool

class superdjango.contrib.support.library.Section(section_name, **kwargs)

Bases: object

An object-oriented representation of a configuration section from an INI file See INIConfig.

__init__(section_name, **kwargs)

Initialize the section.

Parameters

section_name (str) – The section name.

Keyword arguments are added as context variables.

class superdjango.contrib.support.library.Snippet(content, path, **kwargs)

Bases: superdjango.utils.library.File

A fragment of content maintained separate from articles.

__init__(content, path, **kwargs)

Initialize a content snippet.

Parameters

• content (str) – The content of the snippet.

• path (str) – The path to the snippet file.

Keyword arguments are available as dynamic attributes of the instance. tags, if provided, are a comma separated list.

property slug

Get the snippet slug. Complies with the overall API.

Return type

str

to_html(extensions=['extra'])

Export to HTML.

Parameters

extensions (list[str]) – A list of Markdown extensions to apply.

Return type

str

Returns

The content passed through mark_safe().

class superdjango.contrib.support.library.Support(contact=None, email=None, phone=None, url=None, **kwargs)

Bases: object

Encapsulates support information.

__init__(contact=None, email=None, phone=None, url=None, **kwargs)

Initialize support info.

Parameters

• contact (str) – The contact name.

• email (str) – The email address used for contacting support.

• phone (str) – The phone number used for contact support.

• url (str) – The URL for support docs, self-service, etc.

Keyword arguments are available as dynamic attributes.

property path

Get the path to the support file. Complies with the overall API.

Return type

str

property slug

Always returns support. Complies with the overall API.

Return type

str

to_markdown()

Export support info as Markdown.

Return type

str

class superdjango.contrib.support.library.Term(name, area=None, category=None, definition=None, sticky=False, tags=None)

Bases: object

A term and definition.

__init__(name, area=None, category=None, definition=None, sticky=False, tags=None)

Initialize the term.

Parameters

• name (str) – The name of the term being defined.

• area (str) – The area to which the FAQ is belongs.

• category (str) – The category into which FAQ is organized.

• sticky (bool) – Indicates the FAQ should appear at the top of lists.

• tags (str) – A comma separated list of tags used to classify the FAQ.

property content

Get the term and its definition. Complies with the overall API.

Return type

str

property path

Get the path to the terms file. Complies with the overall API.

Return type

str

property slug

Always returns terms.

to_markdown()

Export the term to Markdown.

Return type

str

superdjango.contrib.support.library.factory(path)

Load content based on the given file.

superdjango.contrib.support.library.parse_callout(string)

Parse a given string as callout text.

Parameters

string (str) – The string that might contain a callout.

Return type

str

Note

If not callout is found, the string is returned as is.

superdjango.contrib.support.library.read_ini_file(content_class, path)

Load an INI file.

Parameters

• content_class (class) – The content class to use.

• path (str) – The path to the file.

Returns

A list of Area, FAQ or Term instances, or a Support instance.

Raise

TypeError

superdjango.contrib.support.library.read_markdown_file(path)

Load a Markdown file.

Parameters

path (str) – The path to the file.

Return type

tuple(str, dict)

Returns

The content and meta data.

models

class superdjango.contrib.support.models.HelpComment(*args, **kwargs)

Bases: superdjango.db.audit.models.AddedByModel, superdjango.db.audit.models.ModifiedByModel

A user comment on a specific help page.

Parameters

• id (AutoField) – Id

• added_by_id (ForeignKey) – Added by

• added_dt (AutoNowAddDateTimeField) – Date and time the record was created.

• modified_by_id (ForeignKey) – Modified by

• modified_dt (AutoNowDateTimeField) – Date and time the record was last modified.

• body (TextField) – The comment body.

• page (CharField) – The page identifier where the comment was made.

• subject (CharField) – The title, question, or subject of the comment.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

class superdjango.contrib.support.models.HelpRanking(*args, **kwargs)

Bases: superdjango.db.audit.models.AddedByModel, superdjango.db.audit.models.ModifiedByModel

A user ranking of the usefulness of a specific help page.

Parameters

• id (AutoField) – Id

• added_by_id (ForeignKey) – Added by

• added_dt (AutoNowAddDateTimeField) – Date and time the record was created.

• modified_by_id (ForeignKey) – Modified by

• modified_dt (AutoNowDateTimeField) – Date and time the record was last modified.

• page (CharField) – The page identifier where the ranking was made.

• score (PositiveSmallIntegerField) – The score.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

class superdjango.contrib.support.models.SearchCatalog(*args, **kwargs)

Bases: django.db.models.base.Model

Stores search terms, source files, and URLs used to create search results.

Parameters

• id (AutoField) – Id

• added_dt (AutoNowAddDateTimeField) – Date and time the entry was created.

• modified_dt (AutoNowDateTimeField) – Date and time the entry was last modified.

• page (CharField) – The page identifier where the match was found.

• source_file (CharField) – The original source file/path where the search terms. Note this may change.

• terms (CharField) – The matching search terms.

• total_matches (PositiveSmallIntegerField) – The total number of matches on the page.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

class superdjango.contrib.support.models.SearchResult(*args, **kwargs)

Bases: superdjango.db.audit.models.AddedByModel

Optionally stores user search results. Useful for improving help and the search catalog.

Parameters

• id (AutoField) – Id

• added_by_id (ForeignKey) – Added by

• added_dt (AutoNowAddDateTimeField) – Date and time the entry was created.

• terms (CharField) – The matching search terms.

• total_matches (PositiveSmallIntegerField) – The total number of matches found for the search.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

views

class superdjango.contrib.support.views.AjaxHelpComment(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.ajax.mixins.JSONMixin, django.views.generic.base.View

Submit a help comment via AJAX.

class superdjango.contrib.support.views.AjaxHelpRanking(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.ajax.mixins.JSONMixin, django.views.generic.base.View

Submit a help ranking via AJAX.

class superdjango.contrib.support.views.AjaxLoadHelp(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.ajax.mixins.JSONMixin, django.views.generic.base.View

Load help content for an area of the project.

class superdjango.contrib.support.views.AjaxSearchHelp(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.ajax.mixins.JSONMixin, django.views.generic.base.View

Searches for help content using the search catalog.

class superdjango.contrib.support.views.LoginMayBeRequiredMixin

Bases: superdjango.views.access.AccessMixin

An authenticated user may or may not be required.

class superdjango.contrib.support.views.SupportArticle(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

Responsible for loading specific help content, other than home page content.

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.support.views.SupportFAQs(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

Responsible for loading FAQs.

class superdjango.contrib.support.views.SupportHome(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

The home page for support info.

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.support.views.SupportPage(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

Responsible for loading generic, other than home page content.

get_context_data(**kwargs)

Add breadcrumbs to the context.

class superdjango.contrib.support.views.SupportSearch(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.forms.FormView

The search and search results page.

class superdjango.contrib.support.views.SupportTerms(**kwargs)

Bases: superdjango.contrib.support.views.LoginMayBeRequiredMixin, superdjango.views.breadcrumbs.BreadcrumbsMixin, superdjango.views.templates.TemplateView

Responsible for loading terms and definitions.

class superdjango.contrib.support.views.SupportViewSet(app_name=None, namespace=None)

Bases: superdjango.views.viewsets.ViewSet

Collects all of the support views together.