Core¶

Version: 4.0.0-d

Dependencies

bandit (required) Used to scan SuperDjango for security issues.
semver (required) Used for version management and generating documentation.

Assets¶

Version: 0.7.0-d

Provides access to static files for all other SuperDjango apps and includes resources for programmatically defining JavaScript and CSS.

Developer Reference: Assets

Provides

Library
Static Files

Dependencies

ace (suggested) Code editor used for UI ``CodeControl``.
chartjs (optional) Used to generate charts.
datepicker (required) Used by UI to create a date picker form element. Note: Site says deprecated.
django-dynamic-formset (required) Used by UI for creating formsets.
dragula (required) Used by UI for Kanban lists.
fileuploader (required) Used by UI for AJAX uploads.
jquery-chained (required) Used by UI to automatically create chained select fields.
jquery-mask (required) Used by UI to create masks on form fields.
jquery-sortable (required) Used by UI to provide record sortation.
jquery-timepicker (required) Used by UI to provide a time picker form element.
jquery-toast (required) Used by UI to create toasts.
jquery-wheelcolorpicker (required) Used by UI to provide a color picker form element.
momentjs (required) Used in various ways for time support.
multiselectjs (required) Used by UI to create a multi-select form element.
nicedit (required) Code editor that may be used for UI ``CodeControl``.
notifyjs (required) Used by ``contrib.notifications`` for the `Web Notifications API <http://www.w3.org/TR/notifications/>`_.
select2 (required) Used by UI to create advanced select form elements.
uikit3 (required) Alternative to Twitter Bootstrap.
viewerjs (required) May be used to display documents.
zoom (required) May be used to create an image zoom.

Abstract¶

The assets app provides access to static files for all other SuperDjango apps. This centralized approach may have some disadvantages, but it allows a single entry in INSTALLED_APPS to provide static files for any app, library, or other resource in the SuperDjango suite.

Install¶

Add 'superdjango.assets.apps.DefaultConfig', to INSTALLED_APPS.

Usage¶

Usage is driven primarily by apps within the SuperDjango suite, but developers may wish to make use of the bundled files.

Static Files¶

The structure of static files are divided into 2 categories: bundled and superdjango.

Bundled files are included for convenience, especially during development. These files are more or less organized as provided by the authors or maintainers of the package.

Note

The corresponding licenses are included in the top-level legal/ directory. See Legal.

Files specific to SuperDjango are located in the superdjango/ sub-directory. These are first organized by the app, library, or module that utilizes the component. Individual files are further organized by type, such as css/, fonts/, images/, or js/.

All static files may be accessed in templates in the standard manner:

Conf¶

Version: 4.1.1-d

Manage settings for SuperDjango.

Developer Reference: Conf

Provides

Settings

Dependencies

django-appconf (required) Used to make various SuperDjango settings easier to use.

Abstract¶

There are a large number of settings which control SuperDjango’s behavior. A means of centralizing and documenting these was desired.

Note

Regarding the choice of django-appconf: Prior to SuperDjango 4, various approaches were used and all suffered from one problem or another. The django-appconf app rather nicely meets the need of centralizing settings, and (as of this writing) has 100% code coverage. However, should it need to be replaced, the source code is relatively straight-forward, and could be adapted and modernized if need be.

Context Processors¶

Version: 0.5.0-a

Commonly needed processing that doesn’t necessarily fit within a specific app.

Developer Reference: Context Processors

Provides

Context Processors

Install¶

Add the desired context processor to template options. For example:

TEMPLATES = [
    {
        # ...
        'OPTIONS': {
            'context_processors': [
                # ...
                'superdjango.context_processors.settings_in_context',
                # ...
            ],
        },
    },
]

Constants¶

Version: 0.6.0-d

Constants that may be used across SuperDjango and (optionally) your project.

Developer Reference: Constants

Provides

Constants

Forms¶

Version: 0.10.0-d

Forms, fields, and widgets used across SuperDjango.

Developer Reference: Forms

Provides

Forms : fields, forms, widgets

Abstract¶

The forms app provides general fields and widgets for use in your apps. SuperDjango resources may make use of these as well, especially those in superdjango.db.

Install¶

No installation is required.

Usage¶

TODO

Environment¶

Version: 0.4.1-x

Load configuration variables from an INI file.

Developer Reference: Environment

Provides

Library

Abstract¶

There are lots of ways of dealing with configuration data that should not be hard-coded (and potentially) revealed in the settings.py file. Using environment variables, though recommended by lots of people, is not always possible; they do not work in Apache and may not work with Nginx.

Two notable solutions are django-configurations and django-environ, and developers are encouraged to check these out. SuperDjango offers the env app as a relatively straight-forward means of dealing with configuration data.

Install¶

No installation steps are required to use this package, but see Usage below.

Usage¶

Create an env.ini file in your source directory. This is typically the same directory as the manage.py file.

Important

Be sure to exclude this file from your repo.

Here is an example:

[environment]
name = live
debug = True

[branding]
copyright = ACME, Inc.
logo = images/logo.png
site_title = ACME Technologies
tagline = Rocket skates, explosive birdseed, and more since 1955.

[secret]
key = secret_key

[database]
host = localhost
name = example_com
password = None
user = postgres

[log]
level = DEBUG
path = /path/to/work/example_com/logs

Each section becomes available as an instance variable on the Env instance, meaning (for example) that the database host may be referred to as env.database.host.

Tip

Any variable added to the environment section is available without the use of the environment section name. For example, env.debug instead of env.environment.debug. See example below.

In your settings.py file, import Env and load the INI file:

# settings.py
from superdjang.env import Env

# assuming the file is located at the same level as manage.py ...
env = Env("env.ini")

DEBUG = env.debug
SECRET_KEY = env.secret.key

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': env.database.host,
        'NAME': env.database.name,
        'PASSWORD': env.database.password,
        'USER': env.database.user,
    }
}

BRANDING = env.branding

# ... and so on ...

Exceptions¶

Version: 0.7.0-d

Exceptions for speed, convenience, and humor.

Developer Reference: Exceptions

Provides

Exceptions

HTML¶

Version: 4.0.1-d

An app providing resources for working with HTML in a reasonably abstract manner.

Developer Reference: HTML

Provides

Library
Shortcuts
Templates
Template Tags
Utilities

Dependencies

markdown (suggested) Used by the ``markdown_tags`` template tags module.

Abstract¶

The HTML app provides various an abstracted means of working with frameworks such as Twitter Bootstrap. It takes advantage of Django’s standard means of overriding templates in order to provide a relatively seamless way to implement a given framework’s specific elements.

Additionally, the app provides various resources for working with HTML programmatically.

This app used extensively by SuperDjango UI.

Install¶

Make sure the assets app is in INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'superdjango.assets.apps.DefaultConfig',
]

Pick the framework you wish to use with the project. For example, to use Twitter Bootstrap:

INSTALLED_APPS = [
    # ...
    'superdjango.html.frameworks.bootstrap4',
]

You’ll also need to add FORM_RENDERER in the settings.py file:

FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

Usage¶

After setup, using the html app is more or less automatic across all of SuperDjango.

Overriding Templates

Should you wish to override a template, the usual means is provided. For example, to override the delayed_redirect.html template, create an app and add it to INSTALLED_APPS above your the install of your chosen framework.

INSTALLED_APPS = [
    # ...
    'shared.myhtml.apps.DefaultConfig',
    'superdjango.html.frameworks.bootstrap4.apps.DefaultConfig',
]

In this example, the myhtml app should have a template at superdjango/views/delayed_redirect.html.

Patterns¶

Version: 0.7.2-d

Utilities and backends for file storage.

Developer Reference: Patterns

Provides

Constants
Library

Abstract¶

The patterns library provides a number resources useful for managing URL patterns.

Benefits¶

Pattern constants define the common patterns for use with path() and re_path().
The VersionConverter is a semver.org converter for use with path().
ModelPattern is primarily used by SuperDjango UI, but may also be used programmatically to store URL patterns for later use.

Install¶

There is no special install procedure for this library.

Usage¶

See Reference below.

Sessions¶

Version: 0.4.1-x

Work with Django sessions using an object-oriented interface.

Developer Reference: Sessions

Provides

Library

Abstract¶

There are various things to remember when working with sessions in Django. This simple wrapper makes it easy to work with a Django session in an object-oriented manner.

Install¶

Other than configuring Django sessions there are no installation steps for this package.

Usage¶

To use a session in a view:

from superdjango.sessions import Session

def my_view(request):
    session = Session(request, prefix="myapp")
    session.set("has_viewed_my_view", True)
    # ...

def my_other_view(request):
    session = Session(request, prefix="myapp")
    if not session.has("has_viewed_my_view"):
        redirect(reverse("my_view"))

    # ...

The prefix is optional, but helps prevent collisions. It’s also handy when working with an app that has multiple session variables.

Shortcuts¶

Version: 0.12.1-d

A library of functions and classes that span Django’s MVT framework.

Developer Reference: Shortcuts

Provides

Shortcuts

Abstract¶

Shortcuts provide succinct helpers for various tasks. As with Django’s shortcuts module, these may span multiple levels of MVC, “introducing controlled coupling for the sake of convenience”.

Storage¶

Version: 0.4.0-d

Utilities and backends for file storage.

Developer Reference: Storage

Provides

Constants
Receivers
Signals
Storage
Utilities

Dependencies

boto (optional) Used by the AWS S3 backend.
couch (optional) Used for the Couch DB backend.
pillow (required) Used to generate thumbnails.
pymongo (optional) Used for the Mongo DB backend.

Utilities and backends for file storage.

See https://docs.djangoproject.com/en/stable/ref/files/storage/

Warning

Many of the resources in this package operate in a destructive manner; creating, removing, and updating files.

Setup¶

To use the overwrite storage as the default, add the following to your settings.py file:

# https://docs.djangoproject.com/en/stable/ref/settings/#default-file-storage
DEFAULT_FILE_STORAGE = "superdjango.storage.backends.OverwriteStorage"

Utilities¶

Version: 0.16.0-d

General utilities not necessarily related to Django but nevertheless use for general operation.

Developer Reference: Utilities

Provides

Constants
Utilities

Dependencies

beautifulsoup4 (required) Used to strip HTML tags.

Boolean Operations¶

is_bool¶

Determine if a given value is a boolean at run time.

from superdjango.utils import is_bool

print(is_bool("yes"))
print(is_bool(True))
print(is_bool("No"))
print(is_bool(False))

Tip

By default, a liberal number of values are used to test. If you just want True or False, simply pass (True, False) as test_values.

to_bool¶

Convert a given value to it’s boolean equivalent.

from superdjango.utils import to_bool

print(to_bool("yes"))
print(to_bool(1))
print(to_bool("no"))
print(to_bool(0))

Note that an unrecognized value will raise a value error.

from superdjango.utils import to_bool

value = "not a boolean"
try:
    print(to_bool(value))
except ValueError:
    print('"%s" is not a boolean value.' % value)

File Operations¶

copy_file¶

Copy a file from one location to another.

from superdjango.utils import copy_file

copy_file("readme-template.txt", "path/to/project/readme.txt")

copy_tree¶

Recursively copy a source directory to a given destination.

from superdjango.utils import copy_tree

success = copy_tree("from/path", "to/path")
print(success)

read_csv¶

Read the contents of a CSV file.

menu,identifier,sort_order,text,url
main,product,10,Product,/product/
main,solutions,20,Solutions,/solutions/
main,resources,30,Resources,/resources/
main,support,40,Support,https://support.example.com
main,about,50,About,/about/
main,contact,60,Contact,/contact/

from superdjango.utils import read_csv

rows = read_csv("path/to/menus.csv", first_row_fields_names=True)
for r in rows:
    print("%s: %s" % (row['identifier'], row['url']

read_file¶

Read a file and return its contents.

from superdjango.utils import read_file

output = read_file("path/to/readme.txt")
print(output)

write_file¶

Write a file.

from superdjango.utils import write_file

write_file("path/to/readme.txt", "This is a test.")

Math Helpers¶

average¶

Calculate the average of a given number of values, taking care to handle zero division.

from superdjango.utils import average

values = [1, 2, 3, 4, 5]
print(average(values))

is_integer¶

Indicates whether the given value is an integer. Saves a little typing.

from superdjango.utils import is_integer

print(is_integer(17))
print(is_integer(17.5))
print(is_integer("17"))
print(is_integer("17", cast=True))

percentage¶

Calculate the percentage that a portion makes up of a total.

from superdjango.utils import percentage

p = percentage(50, 100)
print(p + "%")

String Operations¶

base_convert¶

Convert a number between two bases of arbitrary digits.

from superdjango.utils import base_convert

print(base_convert(12345))

camelcase_to_underscore¶

Convert a string from CamelCase to camel_case.

from superdjango.utils import camelcase_to_underscore

model_name = "ProjectTasks"
print(camelcase_to_underscore(model_name))

indent¶

Indent a string.

from superdjango.utils import indent

text = "This text will be indented."
print(indent(text))

is_string¶

Indicates whether the given value is a string. Saves a little typing.

from superdjango.utils import is_string

print(is_string("testing"))
print(is_string("17"))
print(is_string(17))

strip_html_tags¶

Strip HTML tags from a string.

from superdjango.utils import strip_html_tags

html = "<p>This string contains <b>HTML</b> tags.</p>"
print(strip_html_tags(html))

truncate¶

Get a truncated version of a string if if over the limit.

from superdjango.utils import truncate

title = "This Title is Too Long to Be Displayed As Is"
print(truncate(title))

underscore_to_camelcase¶

Convert a string from camel_case to CamelCase .

from superdjango.utils import underscore_to_camelcase

pattern_name = "project_detail"
print(underscore_to_camelcase(pattern_name))

underscore_to_title_case¶

Convert a string from under_score_case to Title Case.

from superdjango.utils import underscore_to_title_case

pattern_name = "project_detail"
print(underscore_to_title_case(pattern_name))

Others¶

The File Class¶

The File class is a simple helper for working with the various attributes of a given file path.

For more robust handling of paths, see pathlib.

from superdjango.utils import File

f = File("/path/to/config.ini")
print("Path: %s" % f.path)
print("Directory: %s" % f.directory)
print("Name: %s" % f.name
print("Name Without Extension: %s" % f.basename)
print("Extension: %s" % f.extension)

smart_cast¶

Intelligently cast the given value to a Python data type.

from superdjango.utils import smart_cast

value = "123"
print(type(smart_cast(value)), smart_cast(value))

value = "yes"
print(type(smart_cast(value)), smart_cast(value))

Views¶

Version: 0.4.1-d

High-level, class-based views that may be used in practically all of the common use cases for Web application development.

Developer Reference: Views

Provides

Views : base, mixins

Abstract¶

High-level, class-based views that may be used in practically all of the common use cases for Web application development. Originally inspired by django-vanilla-views, SuperDjango’s views provide a specific, opinionated, and simpler alternative to Django’s own class-based views.

Install¶

TODO: There are no install steps for views, though we should look at documenting the use of settings.

Usage¶

TODO: Incorporate usage examples for generic views.