Because Django was developed in a fast-paced newsroom environment, it was\ndesigned to make common web development tasks fast and easy. Here’s an informal\noverview of how to write a database-driven web app with Django.
\nThe goal of this document is to give you enough technical specifics to\nunderstand how Django works, but this isn’t intended to be a tutorial or\nreference – but we’ve got both! When you’re ready to start a project, you can\nstart with the tutorial or dive right into\nmore detailed documentation.
\nAlthough you can use Django without a database, it comes with an\nobject-relational mapper in which you describe your database layout in\nPython code.
\nThe data-model syntax offers many rich ways of\nrepresenting your models – so far, it’s been solving many years’ worth of\ndatabase-schema problems. Here’s a quick example:
\nnews/models.pyfrom django.db import models\n\n\nclass Reporter(models.Model):\n full_name = models.CharField(max_length=70)\n\n def __str__(self):\n return self.full_name\n\n\nclass Article(models.Model):\n pub_date = models.DateField()\n headline = models.CharField(max_length=200)\n content = models.TextField()\n reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)\n\n def __str__(self):\n return self.headline\nNext, run the Django command-line utilities to create the database tables\nautomatically:
\nLinux / macOS
$ python manage.py makemigrations\n$ python manage.py migrate\nWindows
...\\> py manage.py makemigrations\n...\\> py manage.py migrate\nThe makemigrations command looks at all your available models and\ncreates migrations for whichever tables don’t already exist. migrate\nruns the migrations and creates tables in your database, as well as optionally\nproviding much richer schema control.
With that, you’ve got a free, and rich, Python API\nto access your data. The API is created on the fly, no code generation\nnecessary:
\n# Import the models we created from our "news" app\n>>> from news.models import Article, Reporter\n\n# No reporters are in the system yet.\n>>> Reporter.objects.all()\n<QuerySet []>\n\n# Create a new Reporter.\n>>> r = Reporter(full_name="John Smith")\n\n# Save the object into the database. You have to call save() explicitly.\n>>> r.save()\n\n# Now it has an ID.\n>>> r.id\n1\n\n# Now the new reporter is in the database.\n>>> Reporter.objects.all()\n<QuerySet [<Reporter: John Smith>]>\n\n# Fields are represented as attributes on the Python object.\n>>> r.full_name\n'John Smith'\n\n# Django provides a rich database lookup API.\n>>> Reporter.objects.get(id=1)\n<Reporter: John Smith>\n>>> Reporter.objects.get(full_name__startswith="John")\n<Reporter: John Smith>\n>>> Reporter.objects.get(full_name__contains="mith")\n<Reporter: John Smith>\n>>> Reporter.objects.get(id=2)\nTraceback (most recent call last):\n ...\nDoesNotExist: Reporter matching query does not exist.\n\n# Create an article.\n>>> from datetime import date\n>>> a = Article(\n... pub_date=date.today(), headline="Django is cool", content="Yeah.", reporter=r\n... )\n>>> a.save()\n\n# Now the article is in the database.\n>>> Article.objects.all()\n<QuerySet [<Article: Django is cool>]>\n\n# Article objects get API access to related Reporter objects.\n>>> r = a.reporter\n>>> r.full_name\n'John Smith'\n\n# And vice versa: Reporter objects get API access to Article objects.\n>>> r.article_set.all()\n<QuerySet [<Article: Django is cool>]>\n\n# The API follows relationships as far as you need, performing efficient\n# JOINs for you behind the scenes.\n# This finds all articles by a reporter whose name starts with "John".\n>>> Article.objects.filter(reporter__full_name__startswith="John")\n<QuerySet [<Article: Django is cool>]>\n\n# Change an object by altering its attributes and calling save().\n>>> r.full_name = "Billy Goat"\n>>> r.save()\n\n# Delete an object with delete().\n>>> r.delete()\nOnce your models are defined, Django can automatically create a professional,\nproduction ready administrative interface –\na website that lets authenticated users add, change and delete objects. The\nonly step required is to register your model in the admin site:
\nnews/models.pyfrom django.db import models\n\n\nclass Article(models.Model):\n pub_date = models.DateField()\n headline = models.CharField(max_length=200)\n content = models.TextField()\n reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)\nnews/admin.pyfrom django.contrib import admin\n\nfrom . import models\n\nadmin.site.register(models.Article)\nThe philosophy here is that your site is edited by a staff, or a client, or\nmaybe just you – and you don’t want to have to deal with creating backend\ninterfaces only to manage content.
\nOne typical workflow in creating Django apps is to create models and get the\nadmin sites up and running as fast as possible, so your staff (or clients) can\nstart populating data. Then, develop the way data is presented to the public.
\nA clean, elegant URL scheme is an important detail in a high-quality web\napplication. Django encourages beautiful URL design and doesn’t put any cruft\nin URLs, like .php or .asp.
To design URLs for an app, you create a Python module called a URLconf. A table of contents for your app, it contains a mapping\nbetween URL patterns and Python callback functions. URLconfs also serve to\ndecouple URLs from Python code.
\nHere’s what a URLconf might look like for the Reporter/Article\nexample above:
news/urls.pyfrom django.urls import path\n\nfrom . import views\n\nurlpatterns = [\n path("articles/<int:year>/", views.year_archive),\n path("articles/<int:year>/<int:month>/", views.month_archive),\n path("articles/<int:year>/<int:month>/<int:pk>/", views.article_detail),\n]\nThe code above maps URL paths to Python callback functions (“views”). The path\nstrings use parameter tags to “capture” values from the URLs. When a user\nrequests a page, Django runs through each path, in order, and stops at the\nfirst one that matches the requested URL. (If none of them matches, Django\ncalls a special-case 404 view.) This is blazingly fast, because the paths are\ncompiled into regular expressions at load time.
\nOnce one of the URL patterns matches, Django calls the given view, which is a\nPython function. Each view gets passed a request object – which contains\nrequest metadata – and the values captured in the pattern.
\nFor example, if a user requested the URL “/articles/2005/05/39323/”, Django\nwould call the function news.views.article_detail(request,\nyear=2005, month=5, pk=39323).
Each view is responsible for doing one of two things: Returning an\nHttpResponse object containing the content for the\nrequested page, or raising an exception such as Http404.\nThe rest is up to you.
Generally, a view retrieves data according to the parameters, loads a template\nand renders the template with the retrieved data. Here’s an example view for\nyear_archive from above:
news/views.pyfrom django.shortcuts import render\n\nfrom .models import Article\n\n\ndef year_archive(request, year):\n a_list = Article.objects.filter(pub_date__year=year)\n context = {"year": year, "article_list": a_list}\n return render(request, "news/year_archive.html", context)\nThis example uses Django’s template system, which\nhas several powerful features but strives to stay simple enough for\nnon-programmers to use.
\nThe code above loads the news/year_archive.html template.
Django has a template search path, which allows you to minimize redundancy\namong templates. In your Django settings, you specify a list of directories to\ncheck for templates with DIRS. If a template\ndoesn’t exist in the first directory, it checks the second, and so on.
Let’s say the news/year_archive.html template was found. Here’s what that\nmight look like:
news/templates/news/year_archive.html{% extends "base.html" %}\n\n{% block title %}Articles for {{ year }}{% endblock %}\n\n{% block content %}\n<h1>Articles for {{ year }}</h1>\n\n{% for article in article_list %}\n <p>{{ article.headline }}</p>\n <p>By {{ article.reporter.full_name }}</p>\n <p>Published {{ article.pub_date|date:"F j, Y" }}</p>\n{% endfor %}\n{% endblock %}\nVariables are surrounded by double-curly braces. {{ article.headline }}\nmeans “Output the value of the article’s headline attribute.” But dots aren’t\nused only for attribute lookup. They also can do dictionary-key lookup, index\nlookup and function calls.
Note {{ article.pub_date|date:"F j, Y" }} uses a Unix-style “pipe” (the “|”\ncharacter). This is called a template filter, and it’s a way to filter the\nvalue of a variable. In this case, the date filter formats a Python datetime\nobject in the given format (as found in PHP’s date function).
You can chain together as many filters as you’d like. You can write\ncustom template filters. You can\nwrite custom template tags, which run\ncustom Python code behind the scenes.
\nFinally, Django uses the concept of “template inheritance”. That’s what the\n{% extends "base.html" %} does. It means “First load the template called\n‘base’, which has defined a bunch of blocks, and fill the blocks with the\nfollowing blocks.” In short, that lets you dramatically cut down on redundancy\nin templates: each template has to define only what’s unique to that template.
Here’s what the “base.html” template, including the use of static files, might look like:
\ntemplates/base.html{% load static %}\n<html lang="en">\n<head>\n <title>{% block title %}{% endblock %}</title>\n</head>\n<body>\n <img src="{% static 'images/sitelogo.png' %}" alt="Logo">\n {% block content %}{% endblock %}\n</body>\n</html>\nSimplistically, it defines the look-and-feel of the site (with the site’s\nlogo), and provides “holes” for child templates to fill. This means that a site\nredesign can be done by changing a single file – the base template.
\nIt also lets you create multiple versions of a site, with different base\ntemplates, while reusing child templates. Django’s creators have used this\ntechnique to create strikingly different mobile versions of sites by only\ncreating a new base template.
\nNote that you don’t have to use Django’s template system if you prefer another\nsystem. While Django’s template system is particularly well-integrated with\nDjango’s model layer, nothing forces you to use it. For that matter, you don’t\nhave to use Django’s database API, either. You can use another database\nabstraction layer, you can read XML files, you can read files off disk, or\nanything you want. Each piece of Django – models, views, templates – is\ndecoupled from the next.
\nThis has been only a quick overview of Django’s functionality. Some more useful\nfeatures:
\nA caching framework that integrates with memcached\nor other backends.
A syndication framework that lets you\ncreate RSS and Atom feeds by writing a small Python class.
More attractive automatically-generated admin features – this overview\nbarely scratched the surface.
The next steps are for you to download Django, read the tutorial and join the community. Thanks for your interest!
\n