Introduction¶

SuperDjango is a collection of tools, utilities, models, fields, and more that make developing with Django quicker and easier.

About This Documentation¶

This documentation is for developers wishing to employ SuperDjango’s resources within their Django project. It is divided into several sections.

Components provides an overview and introduction to all packages included in SuperDjango.
Reference provides implementation details for members within each package.
How-To details a number of use cases and their implementation using SuperDjango’s resources.

Terms and Definitions¶

General¶

$PROJECT_HOME: A convention of virtualenv-wrapper, this is an environment variable which defines the location of where you clone and work on your projects.
$WORKON_HOME: Also a convention of virtualenv-wrapper, this is the location where Python virtual environments are created. Your IDE may utilize this or not. For example, PyCharm automatically creates environments in ~/.virtualenvs/.
display name: A display name is the human-friendly label, title or description of an object – typically a record. A common convention within SuperDjango is to look for a get_display_name() in order to return the most appropriate display to the user.
django root: The location of the Django project; that is, where setttings.py, urls.py, and wsgi.py files are located. Our convention is to use main for the project name.
project root: The top-most directory of a project (not the location of the Django project). This is where project files and directories are stored.
record: A record in SuperDjango’s terminology is always a model instance or connected (in descriptor fashion) to a model instance.
source: The source/ directory is where source code is located. The Django root directory live here.

Component Types¶

SuperDjango is comprised of various components – packages and modules that deliver functionality or provide development resources. These components may be classified by type, which is a rough indication of the overall scope (and size or complexity) of the component.

The component types defined (in order of greatest size or complexity) are:

area: An overall area of functional behavior or resources.
suite: A suite of related applications.
app: A Django app, possibly providing models, forms, views, and other app-specific resources.
interface: A library or (more likely) a Django app which provides an automated or manual API for working with other resources.
library: A collection of re-usable and typically generic resources.
configuration: Settings-level resources that may be referred to or otherwise utilized to configure the behavior of other resources.

Note

SuperDjango UI is both an area and an interface, and also includes configuration.

Stages¶

The version and production stage of packages within SuperDjango are tracked individually. Developers are encouraged to pay close attention to the stage of a package to understand the risks involved in adopting or integrating the package.

The stages are described below:

planning: Indicates the production of a package is currently in planning. There may or may not be functional code, and any code that does exist is likely to be broken, unreliable, and certain to change at some point in the future. Pre-release identifier: -p
experimental: Experimental code may be functional, but untested. It will likely change in the future. Ideas and protoyping play out during this stage. Usage of this code is highly discouraged. Pre-release identifier: -x
development: Code in the development stage is functional, but may be untested and incomplete. It is likely to change in the future. Pre-release identifier: -d
alpha: The alpha stage represents code that is considered feature-complete. That is, any changes are likely to address bugs, or in rare cases, missing functionality. It may or may not be tested. Pre-release identifier: -a
beta: Beta code is feature-complete and has at least some testing. Except for bugs and code review, it is not likely to change in the future. Pre-release identifier: -b
release: The release stage is for code that is complete and tested (as much as possible) and is now considered ready to release with a 1.0 version number. This means the interfaces for the code are defined. Except for bugs, the code is not likely to change. If it does change, the release candidate number is increased. Pre-release identifier: -r
live: Code that is live has been released. It is stable and reasonably tested. Feature enhancements and bug fixes are now part of regular maintenance on the package. Significant enhancements require passage through all of the previous stages. Note that the live stage does not have a pre-release identifier because it is, by definition, already released.
obsolete: The obsolete stage represents code that is deprecated or pending deprecation. Usage of this code is highly discouraged. Although a package made obsolete is technically released (live), a pre-release identifier is added to note the change from live to obsolescence. Pre-release identifier: -o

Provides¶

Each SuperDjango package may be thought of as providing one or more resources for use in project development. These resources may categorized and noted for each package.

The provides categories are as follows:

Admin: Support for the Django Admin. See admin.
AJAX: Integration with SueprDjango’s automated support for AJAX views and URLs.
API: Integration with SuperDjango’s automated support for Django REST Framework See api.
Backends: Exchangeable backends, such as authentication backends.
Checks: Integrates with Django’s checks framework. See checks.
Choices: A list of choices for use in choice fields.
Compat: Compatibility measures are provided for Python or Django version, dependencies, etc.
Constants: Built-in constants for internal and possibly external use.
Context Processors: Custom context processors. See context_processors.
Data: Data in raw or pre-processed formats for consumption both internal and external to the component
Decorators: Decorators for changing or encapsulating functional behavior.
Descriptors: Generic wrappers for specific object types.
Exceptions: Custom exceptions for fun and profit.
Factories: Implementation of one or more factory patterns for the dynamic creation of resources.
Fixtures: Default or sample data.
Forms: Forms, fields, and widgets. See forms.
Hooks: SuperDjango hooks integration.
Library: Re-usable functionality.
Management Commands: Support for command line or cron-based functionality. See management.
Managers: Custom managers or querysets. See managers.
Middleware: Custom middleware. See middleware.
Models: Models (abstract or concrete), model fields, and model mixins. See models.
Receivers: Custom signal handlers. See receivers.
Registry: A registration system in which resources are stored in a registry
Settings: App-specific or possibly global configuration data.
Shortcuts: Resources such as classes and functions that are not safe to call prior to Django being loaded.
Signals: Custom signals. See signals.
Static Files: Static files such as CSS, images, or JavaScript. See static.
Storage: Storage utilities and backends. See storage.
Templates: Full or partial templates for rendering. See templates.
Template Tags: Custom template tags for use in templates. See templatetags.
UI: Integration with SuperDjango UI.
URLs: Custom URLs, typically associated with the app’s views. See urls.
Utilities: Resources such as classes or functions that are safe to call prior to Django being loaded.
Views: Custom views, either standard or class-based. May be base views, mixins, or viewsets. See views.

Dependencies¶

Components may have one or more dependencies, or no dependencies. These are documented in the packages.ini file of the component. At a minimum each dependency describes the package to be installed, but may also provide a comment and status. The status refers to the necessity of installation.

The status descriptions are as follows:

optional: The requirement is optional, typically depending upon the use of some specific feature or resource. The resource may not work as intended without it, but some steps have been taken to ensure minimum or alternative functionality in the absence of the dependency.
suggested: The requirement is suggested for optimal usage. Without it, things may work at reduced efficiency or with fewer capabilities – or may not work at all.
required: The package is required and functionality will most likely result in errors without it. This is the default status.

For SuperDjango developers, the packages.ini file takes the following form:

[package_name]
comment = Optional, but recommended comment
docs = https://docs.example.com
group = assets (or requirements, which is the default)
home = https://example.com
license = BSD3
scm = https://github.com/example/package
status = suggested
support = https://stackoverflow.com/questions/tagged/example

Dependencies may be grouped in one of two overall classifications:

assets: Assets are static files such as CSS, JavaScript, fonts, etc. SuperDjango provides a number of original asset files as well as bundled assets from third-parties where an open source license is available.
requirements: Packages installed via pip. Some effort has been made to minimize the need for third-party packages. When a third-party package is needed, selection is based upon factors such as activity, community support, and test coverage. Some packages are included with the understanding that they may be easily replaced with a native resource should the need arise.
symlinks: SuperDjango does not use the symlink approach as defined by the resrc.org specification for package management.

Roles¶

The SuperDjango project is built and maintained by people filling various roles. These roles establish authorities and responsibilities within the project and may be filled by one or more people.

We define the following roles:

author: The original author of a component.
contributor: Any contributor of bug fixes, features, documentation, testing, and so on.
maintainer: A contributor that maintains a specific component or package, including its tests and code review of the source code which they maintain.
release manager: The release manager is responsible for defining releases, maintaining release notes, and making new releases available to the public.
test manager: The test manager has overall responsibility for managing unit tests and code quality.

All roles must provide a signed Contributor License Agreement. See Legal.