Ein Projekt erstellen

Wenn du Django zum ersten Mal benutzt, musst du es zuerst einrichten, in dem du ein so genanntes Django Projekt generieren läßt, das die Einstellungen für deine Django-Instanz enthält — inklusive Datenbankeinstellungen, Django- und Anwendungs-spezifischer Einstellungen.

Öffne eine Komanndozeile und wechsle mit cd in ein Verzeichnis, in dem du deinen Code speichern möchtest und führe dann das Kommando django-admin.py startproject mysite aus. Damit wird ein mysite Verzeichnis im momentanen Verzeichnis erstellt.

(django-admin.py sollte auf deinem Suchpfad für Befehle sein, wenn du es mit python setup.py installiert hast. Sollte es nicht im Suchpfad zu finden sein, schau im Verzeichnis site-packages/django/bin nach, wobei site-packages ein Verzeichnis deiner Python Installation ist. Du könntest zum Beispiel ein SymLink zu django-admin.py von einem Verzeichnis im Suchpfad anlegen, sowas wie /usr/local/bin.)

Hier also das, was startproject angelegt hat:

mysite/
    __init__.py
    manage.py
    settings.py
    urls.py

Diese Dateien sind:

• __init__.py: Eine leere Datei, die Python anweist, das mysite Verzeichnis als ein Python-Paket anzusehen. (Lies bitte mehr über Pakete in der offziellen Python-Dokumentation, wenn du ein Python-Anfänger bist.)
• manage.py: Ein Kommandozeilen Utility, das dich mit deinem Django Projekt auf verschiedene Art und Weise interagieren läßt.
• settings.py: Einstellungen/Konfiguration für dein Django-Projekt.
• urls.py: Die URL-Konfiguration für dein Django-Projekt — quasi ein “Inhaltsverzeichnis” deiner Django-basierten Webseite.

Validating models...
0 errors found.

Django version 0.96.1, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows).

python manage.py runserver 8080

python manage.py syncdb

Datenmodelle entwerfen

Nun, da ja deine Umgebung — dein “Projekt” — eingerichtet ist, können wir mit der Arbeit anfangen.

Jede Anwendung die du mit Django schreibst besteht aus einem Python-Paket, irgendwo in deinem Python Pfad, das bestimmten Konventionen folgt. Django enthält ein Utility, das automatisch die grundlegende Verzeichnisstruktur einer Anwendung erstellen kann, so dass du dich ganz auf den Code konzentrieren kannst.

In diesem Tutorial erstellen wir unsere Umfrage-Anwendung der Einfachheit halber im Verzeichnis mysite. Die Anwendung wird deswegen an das Projekt gekoppelt sein und Python Code innerhalb der Umfrage-Anwendung immer auf mysite.polls verweisen. Später im Tutorial wird auch erklärt, wie man eine Anwendung entkoppelt, um sie packen und veröffentlichen kann.

Um deine Anwendung zu erstellen, stelle sicher, dass du dich im mysite Verzeichnis befindest und gib folgenden Befehl ein:

python manage.py startapp polls

Das erstellt ein polls Verzeichnis, das wie folgt aussieht:

polls/
    __init__.py
    models.py
    views.py

Diese Verzeichnisstruktur wird deine Umfrage-Anwendung enthalten.

Der erste Schritt, eine Datenbank-basierte Web-Anwendung in Django zu schreiben, ist, die Datenmodelle — quasi das Datenbank-Layout und zusätzliche Metadaten — zu definieren.

In unserer einfachen Umfrage-Anwendung erstellen wir zwei Datenmodelle: polls (Umfragen) und choices (Wahlmöglichkeiten). Eine Umfrage besteht aus einer Frage und einem Veröffentlichungsdatum. Eine Wahlmöglichkeit hat zwei Felder: Der Text der Wahlmöglichkeit und ein Abstimmungszähler. Jede Wahlmöglichkeit ist mit einer Umfrage verbunden.

Diese Konzepte sind repräsentierbar mit einer einfache Python Klasse. Bearbeite die Datei polls/models.py so, dass sie wie folgt aussieht:

from django.db import models

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice = models.CharField(max_length=200)
    votes = models.IntegerField()

Der Code ist recht eindeutig. Jedes Datenmodell wird von einer Klasse repräsentiert, die eine Subklasse von django.db.models.Model ist. Jedes Datenmodell hat eine Vielzahl an Klassenvariablen, die jeweils ein Datenbankfeld repräsentieren.

Jedes Feld wird von einer Instanz einer models.*Field Klasse repräsentiert — z.B. models.CharField für Zeichenkettenfelder und models.DateTimeField für Datumsfelder. Damit teilst du Django mit, welche Art von Daten jedes Feld enthält.

Der Name jeder models.*Field Instanz (z.B question oder pub_date) ist der Feldname in einem maschinell-lesbaren Format, den du in deinem Python Code und die Datenbank als Spaltenname benutzen wird.

Du kannst optional das erste Positionsargument eines Field benutzen, um einen für Menschen lesbaren Namen zu definieren. Dies wird in einigen introspektiven Teilen von Django benutzt und taucht in der Dokumentation auf. Wenn dieses Feld nicht angegeben wird, benutzt Django den maschinell-lesbaren Namen. In unserem Beispiel haben wir einen für Menschen lesbaren Namen nur für Poll.pup_date — ‘date published’ — definiert. Bei allen anderen Feldern dieses Datenmodells ist der maschinell-lesbare Name für den Menschen gut lesbar.

Einige Field Klassen haben erforderlich Elemente. CharField zum Beispiel benötigt das Argument max_length. Dies wird nicht für das Datenbankschema gebraucht, sondern auch für die Validierung, wie wir bald festellen werden.

Bitte beachte auch, dass eine Relation definiert ist, indem models.ForeignKey benutzt wird. Damit weist Django an, dass jede Wahlmöglichkeit genau einer Umfrage zugewiesen wird. Django unterstützt alle üblichen Datenbank Relationen: many-to-one, many-to-many und one-to-one.

Datenmodelle aktivieren

Dieser kleine Code Abschnitt versorgt Django mit sehr viel Informationen. Damit kann Django:

• Ein Datenbankschema für die Anwendung erstellen (CREATE TABLE Anweisungen)
• Eine Python API für den Datenbankzugriff erstellen, mit der man auf die Poll (Umfrage) und Choice (Wahlmöglichkeit) Objekte zugreifen kann.

Aber zuerst müssen wir unserem Projekt sagen, dass die polls Anwendung installiert ist.

Bearbeite die settings.py Datei nochmal und ändere INSTALLED_APPS so, dass es den String mysite.polls enthält und wie folgt aussieht:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'mysite.polls'
)

Nun weiß Django von mysite und der polls Anwendung. Führe nun folgenden Befehl aus:

python manage.py sql polls

Du solltest dann so etwas ähnliches wie folgt sehen (die CREATE TABLE SQL Anweisung für die Umfrage Anwendung):

BEGIN;
CREATE TABLE "polls_poll" (
    "id" serial NOT NULL PRIMARY KEY,
    "question" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),
    "choice" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
COMMIT;

Beachte auch:

• Die exakte Ausgabe variiert und ist abhängig von der eingesetzten Datenbank
• Tabellennamen werden automatisch generiert, in dem der Name der Anwendung (polls) und der kleingeschriebene Name des Datenmodells kombiniert werden — poll und choice. (Dieses Verhalten kann abgeschaltet werden.)
• Primärschlüssel (IDs) werden automatisch hinzugefügt. (Auch das kannst du abschalten.)
• Standardmäßig hängt Django "_id" an den Feldnamen des ForeignKey an. Und ja, auch das kann abgeschaltet werden.
• Die ForeignKey Relation wird explizit mit einer REFERENCES Anweisung hergestellt.
• Da alles an deinen Datenbanktyp angepasst ist, werden Datenbank-spezifische Feldtypen wie auto_increment (MySQL), serial (PostgreSQL) oder integer primary key (SQLite) automatisch gehandhabt. Genauso wie das Quoting von Feldnamen — z.B. das Nutzen von Anführungsstriche oder einfachen Hochkommas. Der Autor dieses Tutorials nutzt PostgreSQL, daher ist die Beispielausgabe oben in PostgreSQL Syntax.
• Der sql Befehl führt nicht wirklich das SQL in deiner Datenbank aus - er gibt nur das SQL aus, was laut Django notwendig ist. Du könntest also das ausgegebene SQL kopieren und in die Kommandozeile deiner Datenbank einfügen. Allerdings bietet Django, wie du gleich sehen wirst, eine einfachere Möglichkeit, das SQL an die Datenbank zu übergeben.

Wenn es dich interessiert, führe doch mal folge Befehle aus:

• python manage.py validate — Überprüft ob irgendwelche Fehler in deinen Datenmodellen vorhanden sind
• python manage.py sqlcustom polls — Gibt für die Anwendung alle benutzerdefinierten SQL Anweisungen (wie Tabellenänderungen oder Constraints) zurück.
• python manage.py sqlclear polls — Gibt die notwendige DROP TABLE Anweisung für diese Anwendung aus, je nachdem welche Tabellen schon in der Datenbank existieren, wenn überhaupt.
• python manage.py sqlindexes polls — Gibt die CREATE INDEX Anweisung für die Anwendung aus.
• python manage.py sqlall polls — Eine Kombination aller SQL Ausgaben der ‘sql’, ‘sqlcustom’ und ‘sqlindexes’ Befehle.

Das Betrachten der Befehlsausgaben kann dir dabei helfen, zu verstehen, was eigentlich bei Django im Hintergrund abläuft.

Jetzt führe bitte syncdb noch einmal aus, damit diese Tabellen in deiner Datenbank angelegt werden:

python manage.py syncdb

Der syncdb Befehl übergibt das SQL von ‘sqlall’ an deine Datenbank für alle Anwendungen in INSTALLED_APPS, die noch nicht in der Datenbank existieren. Dadurch werden die Tabellen, anfänglichen Daten und Indizes all derjenigen Anwendungen erstellt, die du deinem Projekt seit dem letzten Ausführen des syncdb Befehls hinzugefügt hast. syncdb kann so oft aufgerufen werden, wie du willst und wird nur die Tabellen erstellen, die noch nicht existieren.

Lies die django-admin.py Dokumentation für mehr Informationen über das manage.py Utility.

Mit der API herumspielen

Lass uns nun direkt in den interaktiven Python Interpreter springen und ein wenig mit der API von Django herumspielen. Führe folgenden Befehl für den Python Interpreter aus:

python manage.py shell

Wir benutzen diesen Befehl statt “python” einzugeben, weil dir manage.py die Projektumgebung einrichten kann. “Die Projektumgebung einrichten” bedeutet zwei Dinge:

• Den Namen des Projektes mysite dem Python Import Suchpfad sys.path hinzufügen, da einige Teile von Django — um flexibel zu bleiben — auf das Projekt mit der Python-Modul-Schreibweise (z.B. 'mysite.polls.models') zugreifen. Daher muss das mysite Paket auf dem sys.path liegen.

  Wir haben schon ein Beispiel dafür gesehen: Die INSTALLED_APPS Einstellung ist eine Liste mit Paketen in Python-Modul-Schreibweise.

• Die DJANGO_SETTINGS_MODULE Umgebungsvariable setzen, mit der Django den Pfad zu deiner settings.py Datei herausbekommt.

Sobald du im interaktiven Python Interpreter bist, probier die Datenbank API aus:

# Importiere die Datemmodell-Klassen die wir gerade geschrieben haben.
>>> from mysite.polls.models import Poll, Choice

# Noch keine Umfragen im System.
>>> Poll.objects.all()
[]

# Eine neue Umfrage anlegen.
>>> import datetime
>>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())

# Speichere das Objekt in der Datenbank ab, indem du save() explizit aufrufst.
>>> p.save()

# Nun hat das Objekt eine ID. Es kann sein, dass "1L" statt "1" ausgegeben
# wird, abhängig davon, welche Datenbank du einsetzt. Aber das ist auch
# kein Problem und besagt nur, dass dein Datenbank-Backend Integer Werte
# als Python Long Integer zurückgibt.
>>> p.id
1

# Greife auf Datenbankspalten mit Python Attributen zu.
>>> p.question
"What's up?"
>>> p.pub_date
datetime.datetime(2007, 7, 15, 12, 00, 53)

# Ändere Werte, in dem du die Attribute veränderst und dann save() aufrufst.
>>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
>>> p.save()

# objects.all() zeigt alle Umfragen in der Datenbank an.
>>> Poll.objects.all()
[<Poll: Poll object>]

Moment mal, <Poll: Poll object> ist nicht gerade eine sinnvolle Repräsentation des Objektes. Am besten ändern wir das gleich, in dem wir das zuständige Datenmodell (in der Datei polls/models.py) anpassen und eine __unicode__() Methode Poll und Choice hinzufügen:

class Poll(models.Model):
    # ...
    def __unicode__(self):
        return self.question

class Choice(models.Model):
    # ...
    def __unicode__(self):
        return self.choice

Die __unicode__() Methoden sind allerdings nicht nur für ein besseres Verständnis in der interaktiven Eingabeaufforderung sinnvoll, sondern werden auch in Djangos automatisch generiertem Administrationsoberfläche benutzt.

Beachte bitte, dass das alles normale Python Methoden sind. Also lass uns einfach eine benutzerdefinierte Methode für Demonstrationszwecke hinzufügen:

import datetime
# ...
class Poll(models.Model):
    # ...
    def was_published_today(self):
        return self.pub_date.date() == datetime.date.today()

Beachte, dass oben import datetime auf das Python Standard-Modul datetime verweist.

Und jetzt wieder mit python manage.py shell zurück in den interaktiven Python Interpreter:

>>> from mysite.polls.models import Poll, Choice

# Überprüfe, ob unsere __unicode__() Methode funktioniert.
>>> Poll.objects.all()
[<Poll: What's up?>]

# Django bietet eine umfangreiche Abfrage-API die nur aus Argumenten besteht
>>> Poll.objects.filter(id=1)
[<Poll: What's up?>]
>>> Poll.objects.filter(question__startswith='What')
[<Poll: What's up?>]

# Hole die Umfrage aus dem Jahr 2007. Wenn du dieses Tutorial in einem
# anderen Jahr durchführst, kannst du es auch ändern.
>>> Poll.objects.get(pub_date__year=2007)
<Poll: What's up?>

>>> Poll.objects.get(id=2)
Traceback (most recent call last):
    ...
DoesNotExist: Poll matching query does not exist.

# Da die Abfrage mit einem Primärschlüssel sehr oft vorkommt, hält Django
# eine kleine Abkürzung bereit.
# Folgendes ist identisch mit Poll.objects.get(id=1).
>>> Poll.objects.get(pk=1)
<Poll: What's up?>

# Vergewissere dich, das unsere benutzerdefinierte Methode funktioniert.
>>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
False

# Weise der Umfrage einige Wahlmöglichkeiten zu. Der Aufruf von create
# stellt ein neues choice Objekt her, führt die INSERT Anweisung durch,
# fügt das choice-Objekt (die Wahlmöglichkeit) zu den verfügbaren
# Wahlmöglichkeiten und gibt am Ende das neue Objekt zurück.
>>> p = Poll.objects.get(pk=1)
>>> p.choice_set.create(choice='Not much', votes=0)
<Choice: Not much>
>>> p.choice_set.create(choice='The sky', votes=0)
<Choice: The sky>
>>> c = p.choice_set.create(choice='Just hacking again', votes=0)

# choice-Objekte (Wahlmöglichkeiten) haben API-Zugriff auf ihren zugehörigen
Umfrage Objekte.
>>> c.poll
<Poll: What's up?>

# Andersherum auch: Umfrage-Objekte (polls) haben Zugriff auf
# Wahlmöglichkeits-Objekte (choice).
>>> p.choice_set.all()
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
>>> p.choice_set.count()
3

# Die API folgt allen Relationen so weit du willst. Benutze doppelte
# Unterstriche (__) um Relationen voneinander abzutrennen.
# Das funktioniert in unendlich vielen Ebenen, es gibt praktisch kein Limit.
# Finde alle Wahlmöglichkeiten für alle Umfragen deren Veröffentlichungsdatum
# (pub_date) 2007 ist.
>>> Choice.objects.filter(poll__pub_date__year=2007)
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

# Und nun löschen wir eine der Wahlmöglichkeiten. Benutze delete() dafür.
>>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()

Für mehr Information zur Datenbak API schau bitte in die Databank API Referenz.

Wenn du dich mit der API vertraut gemacht hast, lies Teil 2 dieses Tutorials, um etwas über Djangos automatisches Administrationsoberfläche zu erfahren.