Cookiecutter Django App

This repository provides a Cookiecutter template for creating a reusable Django application. The generated project includes a Django application, a demonstration project, a REST API, Sphinx documentation, and code quality tools configured with Poetry.

Requirements

• Python 3.12 or a later compatible version;
• Poetry;
• PostgreSQL to run the generated Django project;
• Cookiecutter, installed directly or through this repository's dependencies.

Using the cookiecutter

From the Git repository

Cookiecutter can generate a project without cloning this repository first:

cookiecutter gh:dbchiro/DjangoAppTemplate

To use a specific branch or tag:

cookiecutter gh:dbchiro/DjangoAppTemplate --checkout <branch-or-tag>

From a local copy

Clone the repository, install its dependencies, and then run Cookiecutter from its parent directory so that the generated project is not created inside the template repository:

git clone git@github.com:dbchiro/DjangoAppTemplate.git
cd DjangoAppTemplate
poetry install
cd ..
poetry --directory DjangoAppTemplate run cookiecutter DjangoAppTemplate

If Cookiecutter is already installed in your environment, you can replace the last command with:

cookiecutter DjangoAppTemplate

Cookiecutter will then prompt you for a series of values. Press Enter to accept the suggested value shown in brackets.

Available parameters

Parameter	Purpose	Default value
project_name	Human-readable project name and name of the generated directory	My Awesome Project
project_slug	Python package name derived from the project name	my_awesome_project
description	Short package description	Behold My Awesome Project!
author_name	Name of the author or organization	My Wonder Name
domain_name	Domain name available in the templates	example.com
email	Package contact email address	derived from author_name
version	Initial version	0.1.0
open_source_license	License to apply to the project	MIT
homepage_url	Homepage published in the Poetry metadata	https://github.com/...
repository_url	Source repository published in the Poetry metadata	https://github.com/...

The project_slug must be a valid Python identifier. It is used as both the importable package name and the Poetry package name.

Non-interactive generation

For scripts or continuous integration, values can be supplied on the command line:

cookiecutter gh:dbchiro/DjangoAppTemplate \
  --no-input \
  project_name="My application" \
  description="A reusable Django application" \
  author_name="My organization" \
  email="contact@example.com" \
  homepage_url="https://example.com/my-application" \
  repository_url="https://github.com/example/my-application"

After generating the project

Change to the generated directory and install the dependencies:

cd "My application"
poetry install

The demonstration project reads its configuration from the following environment variables:

SECRET_KEY=change-me
DEBUG=True
DBNAME=my_awesome_project
DBUSER=postgres
DBPASSWORD=postgres
DBHOST=localhost
DBPORT=5432
EMAIL_HOST=localhost
EMAIL_PORT=1025
EMAIL_HOST_USER=
EMAIL_HOST_PASSWORD=
EMAIL_USE_TLS=False

These values can, for example, be placed in a .env file at the root of the generated project. Never commit production secrets. After creating the corresponding PostgreSQL database, initialize Django and start the development server:

poetry run python manage.py migrate
poetry run python manage.py createsuperuser
poetry run python manage.py runserver

The following interfaces are then available:

• Django administration: http://127.0.0.1:8000/admin/;
• Swagger documentation: http://127.0.0.1:8000/swagger/;
• ReDoc documentation: http://127.0.0.1:8000/redoc/;
• API authentication: http://127.0.0.1:8000/api-auth/.

Generated project structure

<project_name>/
├── <project_slug>/    # reusable Django application package
├── config/            # demonstration project configuration
├── docs/              # Sphinx documentation
├── manage.py
├── Makefile
├── pyproject.toml
├── README.md
└── CHANGELOG.md

The config directory lets you develop and test the application without having to create a separate Django project. It is not included in the distributed Python package.

Development commands

The generated project's Makefile provides the main development commands:

make test        # run the Django test suite
make check       # apply isort and Black, then run Flake8
make pylint      # run Pylint with the Django plugin
make build-docs  # build the Sphinx documentation
make docs        # build the documentation and model graph

These commands can also be run directly with poetry run. The generated HTML documentation is available in docs/_build/html/.

Developing this template

Install the development dependencies and run the Cookiecutter test suite with:

poetry install
poetry run pytest

The tests render projects with both default and custom values, check the generated structure and metadata, detect unresolved template variables, and compile every generated Python file.

After modifying the cookiecutter, generate a test project in a temporary directory and verify its dependencies and configuration:

cookiecutter . --no-input --output-dir /tmp
cd "/tmp/My Awesome Project"
poetry install
poetry run python manage.py check
poetry run python manage.py test

Files located in {{ cookiecutter.project_name }}/ are Jinja templates. Keep the {{ cookiecutter.* }} expressions required for their customization.

License

This template is distributed under the AGPLv3 license. The contents of the generated project's LICENSE file are selected through the open_source_license parameter.