Interfaces¶

Tools for automating interactions.

Version: 0.1.0-x

AJAX¶

Version: 0.5.0-x

Conveniently and consistently register AJAX views across a project.

Developer Reference: AJAX

Provides

Library
Registry

Abstract¶

The apps within a project often require the creation of AJAX views. These may be ad hoc or part of a more organized structure. SuperDjango’s AJAX app provides a simple interface for registering AJAX views across a project.

Install¶

Update project settings:

# settings.py
INSTALLED_APPS = [
    # ...
    "superdjango.interfaces.ajax.apps.AutoConfig",
    # ...
]

# Default module name is ajax.
SUPERDJANGO_AJAX_MODULE_NAME = "ajax"

If you wish to manually manage an AJAX registry, use superdjango.ajax.apps.DefaultConfig instead.

Utilize the URLs:

# main/urls.py
from superdjango.interfaces.ajax import ajax

urlpatterns = [
    # ...
    path('ajax/', include(ajax.get_urls())),
    # ...
]

Usage¶

Create your AJAX views as normal, utilizing a viewset to capture the views within your app:

# views.py
from superdjango.views import GenericView, JSONMixin, ViewSet

class SomeAjaxCall(JSONMixin, GenericView):
    # ...

class SomeOtherAjaxCall(JSONMixin, GenericView):
    # ...

class MyAjaxViewSet(ViewSet):
    views = [
        SomeAjaxCall,
        SomeOtherAjaxCall,
    ]

# ajax.py
from superdjango.ajax import ajax
from .views import MyAjaxViewSet

ajax.register("myapp", MyAjaxViewSet)

You could, of course, home your AJAX views in the views.py of your app instead of the ajax.py.

CLI¶

Version: 0.2.0-x

Utilities for working with command line interfaces.

Developer Reference: CLI

Provides

Constants
Library

Dependencies

tabulate (required) Used to print tabulate output on the command line.

Hooks¶

Version: 0.4.0-x

A simple alternative to Django’s signal handling system.

Developer Reference: Hooks

Provides

Library
Registry

Abstract¶

Inspired by Wagtail’s hooks, SuperDjango’s hooks system is simple, yet powerful alternative to Django’s signals and receivers.

Install¶

No additional installation steps are required to use hooks.

Usage¶

Defining a Hook¶

Hooks may be defined anywhere in code that is loaded and executed as part of Django operation. For example, the superdjango.contrib.accounts.auth.views.LoginRedirect view defines a hook that may be used to override the post-login redirect URL:

from superdjango.interfaces.hooks import hooks

class LoginRedirect(RedirectView):
    # ...

    def get_redirect_url(self, *args, **kwargs):
        results = hooks.get_hooks("get_login_redirect_url")
        if results:
            return results[0](self.request)

        # ...

Documenting a Hook¶

To help others understand how a hook works, you may define the hook in the meta.ini file of the app or package. For example:

[hooks]
get_login_redirect_url = (request): Return a URL string to override the post-login redirect behavior.

Auto-documentation scripts may now provide a list of provided hooks dynamically.

Responding to a Hook¶

Responding to a hook requires 1) defining a function, 2) registering the function, and 3) making sure the code is loaded. For example:

# myapp/hooks.py
from superdjango.interfaces.hooks import hooks

def get_login_redirect_url(request):
    if request.user.is_superuser:
        return "/admin/"
    else:
        return "/"

hooks.register(get_login_redirect_url, hook="get_login_redirect_url")

The hook name, if omitted defaults to the name of the provided function. So the register statement could simply be written as:

hooks.register(get_login_redirect_url)

Finally, you can use the ready() method to load the hooks:

# myapp/apps.py
from django.apps import AppConfig

class DefaultConfig(AppConfig):
    name = 'myapp'

    def ready(self):
        from . import hooks

REST¶

Version: 0.5.0-x

A lightweight interface for easily registering Django REST Framework resources.

Developer Reference: REST

Provides

Library
Registry

Abstract¶

Projects and apps that implement a REST API often choose Django REST Framework. This package focuses on making the registration of REST resources easy; it’s usefulness is derived from a simple yet effective system of definition and auto-discovery of REST APIs across a project.

Benefits include:

Use Django REST Framework as usual, but with auto-discovery of API resources.
Consistent view names that use a convention similar to the Django Admin to avoid collisions.
Built-in support for new API versions.

Install¶

Django REST Framework is required:

pip install django-rest-framework;

Update project settings:

# settings.py
INSTALLED_APPS = [
    "rest_framework",
    # ...
    "superdjango.interfaces.reset.apps.AutoConfig",
    # ...
]

SUPERDJANGO_API_MODULE_NAME = "api"

The SUPERDJANGO_API_MODULE_NAME may be used to identify the package or module name used to find your API definition. It defaults to api, but may be set to anything you like, provided it is consistent across your project.

Utilize the URLs:

# main/urls.py
from rest_framework import routers
from superdjango.interfaces.reset import api

router = routers.DefaultRouter()

urlpatterns = [
    # ...
    path('api/v1/', include(api.get_urls(router))),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    # ...
]

Usage¶

Create serializers and viewsets. See Django REST Framework Quickstart.

In the __init__.py of the app’s api module, create and register the interface.

# api/__init__.py
from superdjango.interfaces.reset import api, REST
from .views import MyViewSet, MyOtherViewSet

class MyAPI(REST):
    viewsets = [
        MyViewSet,
        MyOtherViewSet,
    ]

api.register("myapp", MyAPI)