/
tutorial01.txt
541 lines (398 loc) · 20.5 KB
/
tutorial01.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
=====================================
Writing your first Django app, part 1
=====================================
By Adrian Holovaty <holovaty@gmail.com>
Let's learn by example.
Throughout this tutorial, we'll walk you through the creation of a simple Web
poll application.
It'll consist of two parts:
* A public site that lets people vote in polls and view poll results.
* An admin site that lets you add, change and delete polls behind the scenes.
We'll assume you have `Django installed`_ already.
.. _`Django installed`: http://www.djangoproject.com/documentation/install/
Initial setup
=============
If this is your first time using Django, you'll have to take care of some
initial setup.
Run the command ``django-admin.py startproject myproject``. That'll create a
``myproject`` directory in your current directory.
(``django-admin.py`` should be on your system path if you installed Django via
its setup.py utility. If it's not on your path, you can find it in
``site-packages/django/bin``; consider symlinking to it from some place
on your path, such as /usr/local/bin.)
.. admonition:: Where should this code live?
If your background is in PHP, you're probably used to putting code under the
Web server's document root (in a place such as ``/var/www``). With Django,
you don't do that. It's not a good idea to put any of this Python code within
your Web server's document root, because it risks the possibility that
people may be able to view your code over the Web. That's not good for
security.
Put your code in some directory **outside** of the document root, such as
``/home/mycode``.
A project is a collection of settings for an instance of Django -- including
database configuration, Django-specific options and application-specific
settings. Let's look at what ``startproject`` created::
myproject/
__init__.py
manage.py
settings.py
urls.py
These files are:
* ``manage.py``: A command-line utility that lets you interact with this
Django project in various ways.
* ``settings.py``: Settings/configuration for this Django project.
* ``urls.py``: The URL declarations for this Django project; a "table of
contents" of your Django-powered site.
The development server
----------------------
Change into the ``myproject`` directory, if you haven't already, and run the
command ``python manage.py runserver``. You'll see the following output on the
command line::
Validating models...
0 errors found.
Django version 0.92, using settings 'myproject.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C (Unix) or CTRL-BREAK (Windows).
(If you get an error about ``DATABASE_ENGINE``, edit your ``settings.py`` file
to change the ``DATABASE_ENGINE`` setting to point to the correct database, and
make sure you have the right database libraries installed -- such as PostgreSQL's
psycopg or MySQL's MySQLdb.)
You've started the Django development server, a lightweight, pure-Python Web
server that builds on the BaseHTTPServer included in Python's standard library.
We've included this with Django so you can develop things rapidly, without
having to deal with configuring Apache until you're ready for production.
DON'T use this server in anything resembling a production environment. It's
intended only for use while developing.
.. admonition:: Changing the port
By default, the ``runserver`` command starts the development server on port
8000. If you want to change the server's port, pass it as a command-line
argument::
python manage.py runserver 8080
Now that the server's running, visit http://127.0.0.1:8000/ with your Web
browser. You'll see a "Welcome to Django" page, in pleasant, light-blue pastel.
It worked!
Database setup
--------------
Now, edit ``settings.py``. It's a normal Python module with module-level
variables representing Django settings. Change these settings to match your
database's connection parameters:
* ``DATABASE_ENGINE`` -- Either 'postgresql', 'mysql' or 'sqlite3'.
More coming soon.
* ``DATABASE_NAME`` -- The name of your database, or the full (absolute)
path to the database file if you're using SQLite.
* ``DATABASE_USER`` -- Your database username (not used for SQLite).
* ``DATABASE_PASSWORD`` -- Your database password (not used for SQLite).
* ``DATABASE_HOST`` -- The host your database is on. Leave this as an
empty string if your database server is on the same physical machine
(not used for SQLite).
.. admonition:: Note
Make sure you've created a database within PostgreSQL or MySQL by this
point. Do that with "``CREATE DATABASE database_name;``" within your
database's interactive prompt.
While you're editing ``settings.py``, take note of the ``INSTALLED_APPS``
setting. That variable holds the names of all Django applications that are
activated in this Django instance. Apps can be used in multiple projects,
and you can distribute them.
By default, ``INSTALLED_APPS`` contains the following apps, all of which come
with Django::
* ``django.contrib.auth`` -- An authentication system.
* ``django.contrib.contenttypes`` -- A framework for content types.
* ``django.contrib.sessions`` -- A session framework.
* ``django.contrib.sites`` -- A framework for managing multiple sites
with one Django installation.
These applications are included by default as a convenience for the common case.
Each of these applications makes use of at least one database table, though,
so we need to create the tables in the database before we can use them. To do
that, run the following command::
python manage.py syncdb
The ``syncdb`` command looks at the ``INSTALLED_APPS`` setting and creates any
necessary database tables according to the database settings in your
``settings.py`` file. You'll see a message for each database table it creates,
and you'll get a prompt asking you if you'd like to create a superuser account
for the authentication system. Go ahead and do that.
If you're interested, run the command-line client for your database and type
``\dt`` (PostgreSQL), ``SHOW TABLES;`` (MySQL), or ``.schema`` (SQLite) to
display the tables Django created.
.. admonition:: For the minimalists
Like we said above, the default applications are included for the common
case, but not everybody needs them. If you don't need any or all of them,
feel free to comment-out or delete the appropriate line(s) from
``INSTALLED_APPS`` before running ``syncdb``. The ``syncdb`` command will
only create tables for apps in ``INSTALLED_APPS``.
Creating models
===============
Now that your environment -- a "project" -- is set up, you're set to start
doing work.
Each application you write in Django consists of a Python package, somewhere
on your `Python path`_, that follows a certain convention. Django comes with a
utility that automatically generates the basic directory structure of an app,
so you can focus on writing code rather than creating directories.
.. admonition:: Projects vs. apps
What's the difference between a project and an app? An app is a Web
application that does something -- e.g., a weblog system, a database of
public records or a simple poll app. A project is a collection of
configuration and apps for a particular Web site. A project can contain
multiple apps. An app can be in multiple projects.
In this tutorial, we'll create our poll app in the ``myproject`` directory,
for simplicity. As a consequence, the app will be coupled to the project --
that is, Python code within the poll app will refer to ``myproject.polls``.
Later in this tutorial, we'll discuss decoupling your apps for distribution.
To create your app, make sure you're in the ``myproject`` directory and type
this command::
python manage.py startapp polls
That'll create a directory ``polls``, which is laid out like this::
polls/
__init__.py
models.py
views.py
This directory structure will house the poll application.
The first step in writing a database Web app in Django is to define your models
-- essentially, your database layout, with additional metadata.
.. admonition:: Philosophy
A model is the single, definitive source of data about your
data. It contains the essential fields and behaviors of the data you're
storing. Django follows the `DRY Principle`_. The goal is to define your
data model in one place and automatically derive things from it.
In our simple poll app, we'll create two models: polls and choices. A poll has
a question and a publication date. A choice has two fields: the text of the
choice and a vote tally. Each choice is associated with a poll.
These concepts are represented by simple Python classes. Edit the
``polls/models.py`` file so it looks like this::
from django.db import models
class Poll(models.Model):
question = models.CharField(maxlength=200)
pub_date = models.DateTimeField('date published')
class Choice(models.Model):
poll = models.ForeignKey(Poll)
choice = models.CharField(maxlength=200)
votes = models.IntegerField()
The code is straightforward. Each model is represented by a class that
subclasses ``django.db.models.Model``. Each model has a number of class
variables, each of which represents a database field in the model.
Each field is represented by an instance of a ``models.*Field`` class -- e.g.,
``models.CharField`` for character fields and ``models.DateTimeField`` for
datetimes. This tells Django what type of data each field holds.
The name of each ``models.*Field`` instance (e.g. ``question`` or ``pub_date`` )
is the field's name, in machine-friendly format. You'll use this value in your
Python code, and your database will use it as the column name.
You can use an optional first positional argument to a ``Field`` to designate a
human-readable name. That's used in a couple of introspective parts of Django,
and it doubles as documentation. If this field isn't provided, Django will use
the machine-readable name. In this example, we've only defined a human-readable
name for ``Poll.pub_date``. For all other fields in this model, the field's
machine-readable name will suffice as its human-readable name.
Some ``Field`` classes have required elements. ``CharField``, for example,
requires that you give it a ``maxlength``. That's used not only in the database
schema, but in validation, as we'll soon see.
Finally, note a relationship is defined, using ``models.ForeignKey``. That tells
Django each Choice is related to a single Poll. Django supports all the common
database relationships: many-to-ones, many-to-manys and one-to-ones.
.. _`Python path`: http://docs.python.org/tut/node8.html#SECTION008110000000000000000
.. _DRY Principle: http://c2.com/cgi/wiki?DontRepeatYourself
Activating models
=================
That small bit of model code gives Django a lot of information. With it, Django
is able to:
* Create a database schema (``CREATE TABLE`` statements) for this app.
* Create a Python database-access API for accessing Poll and Choice objects.
But first we need to tell our project that the ``polls`` app is installed.
.. admonition:: Philosophy
Django apps are "pluggable": You can use an app in multiple projects, and
you can distribute apps, because they don't have to be tied to a given
Django installation.
Edit the ``settings.py`` file again, and change the ``INSTALLED_APPS`` setting
to include the string ``'myproject.polls'``. So it'll look like this::
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'myproject.polls',
)
(Don't forget the trailing comma, because of Python's rule about single-value
tuples: Without a trailing comma, Python wouldn't know this was a tuple.)
Now Django knows ``myproject`` includes the ``polls`` app. Let's run another command::
python manage.py sql polls
You should see the following (the CREATE TABLE SQL statements for the polls app)::
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_polls" ("id"),
"choice" varchar(200) NOT NULL,
"votes" integer NOT NULL
);
COMMIT;
Note the following:
* Table names are automatically generated by combining the name of the app
(``polls``) and the lowercase name of the model -- ``poll`` and
``choice``. (You can override this behavior.)
* Primary keys (IDs) are added automatically. (You can override this, too.)
* By convention, Django appends ``"_id"`` to the foreign key field name.
Yes, you can override this, as well.
* The foreign key relationship is made explicit by a ``REFERENCES`` statement.
* It's tailored to the database you're using, so database-specific field
types such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or
``integer primary key`` (SQLite) are handled for you automatically. Same
goes for quoting of field names -- e.g., using double quotes or single
quotes. The author of this tutorial runs PostgreSQL, so the example
output is in PostgreSQL syntax.
If you're interested, also run the following commands:
* ``python manage.py sqlinitialdata polls`` -- Outputs any initial data
required for Django's admin framework and your models.
* ``python manage.py sqlclear polls`` -- Outputs the necessary ``DROP
TABLE`` statements for this app, according to which tables already exist
in your database (if any).
* ``python manage.py sqlindexes polls`` -- Outputs the ``CREATE INDEX``
statements for this app.
* ``python manage.py sqlall polls`` -- A combination of 'sql' and
'sqlinitialdata'.
Looking at the output of those commands can help you understand what's actually
happening under the hood.
Now, run ``syncdb`` again to create those model tables in your database::
python manage.py syncdb
As a review, the ``syncdb`` command creates the tables for all apps in
``INSTALLED_APPS`` that don't already exist in your database. So you can run it
again and again, and it'll always just create the tables that don't exist.
Read the `django-admin.py documentation`_ for full information on what the
``manage.py`` utility can do.
.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/
Playing with the API
====================
Now, let's hop into the interactive Python shell and play around with the free
API Django gives you. To invoke the Python shell, use this command::
python manage.py shell
We're using this instead of simply typing "python", because ``manage.py`` sets
up the project's environment for you. "Setting up the environment" involves two
things:
* Putting ``myproject`` on ``sys.path``. For flexibility, several pieces of
Django refer to projects in Python dotted-path notation (e.g.
``'myproject.polls.models'``). In order for this to work, the
``myproject`` package has to be on ``sys.path``.
We've already seen one example of this: the ``INSTALLED_APPS`` setting is
a list of packages in dotted-path notation.
* Setting the ``DJANGO_SETTINGS_MODULE`` environment variable, which gives
Django the path to your ``settings.py`` file.
.. admonition:: Bypassing manage.py
If you'd rather not use ``manage.py``, no problem. Just make sure
``myproject`` is at the root level on the Python path (i.e.,
``import myproject`` works) and set the ``DJANGO_SETTINGS_MODULE``
environment variable to ``myproject.settings``.
For more information on all of this, see the `django-admin.py documentation`_.
Once you're in the shell, explore the database API::
# Import the model classes we just wrote.
>>> from myproject.polls.models import Poll, Choice
# No polls are in the system yet.
>>> Poll.objects.all()
[]
# Create a new Poll.
>>> from datetime import datetime
>>> p = Poll(question="What's up?", pub_date=datetime.now())
# Save the object into the database. You have to call save() explicitly.
>>> p.save()
# Now it has an ID. Note that this might say "1L" instead of "1", depending
# on which database you're using. That's no biggie; it just means your
# database backend prefers to return integers as Python long integer
# objects.
>>> p.id
1
# Access database columns via Python attributes.
>>> p.question
"What's up?"
>>> p.pub_date
datetime.datetime(2005, 7, 15, 12, 00, 53)
# Change values by changing the attributes, then calling save().
>>> p.pub_date = datetime(2005, 4, 1, 0, 0)
>>> p.save()
# get_list() displays all the polls in the database.
>>> Poll.objects.all()
[<Poll object>]
Wait a minute. ``<Poll object>`` is, utterly, an unhelpful representation of
this object. Let's fix that by editing the polls model
(in the ``polls/models.py`` file) and adding a ``__repr__()`` method to
both ``Poll`` and ``Choice``::
class Poll(models.Model):
# ...
def __repr__(self):
return self.question
class Choice(models.Model):
# ...
def __repr__(self):
return self.choice
It's important to add ``__repr__()`` methods to your models, not only for your
own sanity when dealing with the interactive prompt, but also because objects'
representations are used throughout Django's automatically-generated admin.
Note these are normal Python methods. Let's add a custom method, just for
demonstration::
class Poll(models.Model):
# ...
def was_published_today(self):
import datetime
return self.pub_date.date() == datetime.date.today()
Note the addition of ``import datetime`` to reference Python's standard
``datetime`` module.
Let's jump back into the Python interactive shell by running
``python manage.py shell`` again::
>>> from myproject.polls.models import Poll, Choice
# Make sure our __repr__() addition worked.
>>> Poll.objects.all()
[What's up?]
# Django provides a rich database lookup API that's entirely driven by
# keyword arguments.
>>> Poll.objects.filter(id=1)
[What's up?]
>>> Poll.objects.filter(question__startswith='What')
[What's up?]
# Get the poll whose year is 2005. Of course, if you're going through this
# tutorial in another year, change as appropriate.
>>> Poll.objects.get(pub_date__year=2005)
What's up?
>>> Poll.objects.get(id=2)
Traceback (most recent call last):
...
DoesNotExist: Poll does not exist for {'id': 2}
>>> Poll.objects.filter(question__startswith='What')
[What's up?]
# Lookup by a primary key is the most common case, so Django provides a
# shortcut for primary-key exact lookups.
# The following is identical to Poll.objects.get(id=1).
>>> Poll.objects.get(pk=1)
What's up?
# Make sure our custom method worked.
>>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
False
# Give the Poll a couple of Choices. Each one of these method calls does an
# INSERT statement behind the scenes and returns the new Choice object.
>>> p = Poll.objects.get(pk=1)
>>> p.choice_set.add(choice='Not much', votes=0)
Not much
>>> p.choice_set.add(choice='The sky', votes=0)
The sky
>>> c = p.choice_set.add(choice='Just hacking again', votes=0)
# Choice objects have API access to their related Poll objects.
>>> c.poll
What's up?
# And vice versa: Poll objects get access to Choice objects.
>>> p.choice_set.all()
[Not much, The sky, Just hacking again]
>>> p.choice_set.all().count()
3
# The API automatically follows relationships as far as you need.
# Use double underscores to separate relationships.
# This works as many levels deep as you want. There's no limit.
# Find all Choices for any poll whose pub_date is in 2005.
>>> Choice.objects.filter(poll__pub_date__year=2005)
[Not much, The sky, Just hacking again]
# Let's delete one of the choices. Use delete() for that.
>>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()
For full details on the database API, see our `Database API reference`_.
When you're comfortable with the API, read `part 2 of this tutorial`_ to get
Django's automatic admin working.
.. _Database API reference: http://www.djangoproject.com/documentation/db_api/
.. _part 2 of this tutorial: http://www.djangoproject.com/documentation/tutorial2/