/docs/intro/tutorial01.txt
Plain Text | 701 lines | 513 code | 188 blank | 0 comment | 0 complexity | 2631b621f3e9e438226499a870af701f MD5 | raw file
1===================================== 2Writing your first Django app, part 1 3===================================== 4 5Let's learn by example. 6 7Throughout this tutorial, we'll walk you through the creation of a basic 8poll application. 9 10It'll consist of two parts: 11 12 * A public site that lets people view polls and vote in them. 13 * An admin site that lets you add, change and delete polls. 14 15We'll assume you have :doc:`Django installed </intro/install>` already. You can 16tell Django is installed by running the Python interactive interpreter and 17typing ``import django``. If that command runs successfully, with no errors, 18Django is installed. 19 20.. admonition:: Where to get help: 21 22 If you're having trouble going through this tutorial, please post a message 23 to `django-users`__ or drop by `#django on irc.freenode.net`__ to chat 24 with other Django users who might be able to help. 25 26__ http://groups.google.com/group/django-users 27__ irc://irc.freenode.net/django 28 29Creating a project 30================== 31 32If this is your first time using Django, you'll have to take care of some 33initial setup. Namely, you'll need to auto-generate some code that establishes a 34Django :term:`project` -- a collection of settings for an instance of Django, 35including database configuration, Django-specific options and 36application-specific settings. 37 38From the command line, ``cd`` into a directory where you'd like to store your 39code, then run the following command: 40 41.. code-block:: bash 42 43 django-admin.py startproject mysite 44 45This will create a ``mysite`` directory in your current directory. 46 47.. admonition:: Script name may differ in distribution packages 48 49 If you installed Django using a Linux distribution's package manager 50 (e.g. apt-get or yum) ``django-admin.py`` may have been renamed to 51 ``django-admin``. You may continue through this documentation by omitting 52 ``.py`` from each command. 53 54.. admonition:: Mac OS X permissions 55 56 If you're using Mac OS X, you may see the message "permission denied" when 57 you try to run ``django-admin.py startproject``. This is because, on 58 Unix-based systems like OS X, a file must be marked as "executable" before it 59 can be run as a program. To do this, open Terminal.app and navigate (using 60 the ``cd`` command) to the directory where :doc:`django-admin.py 61 </ref/django-admin>` is installed, then run the command 62 ``chmod +x django-admin.py``. 63 64.. note:: 65 66 You'll need to avoid naming projects after built-in Python or Django 67 components. In particular, this means you should avoid using names like 68 ``django`` (which will conflict with Django itself) or ``test`` (which 69 conflicts with a built-in Python package). 70 71:doc:`django-admin.py </ref/django-admin>` should be on your system path if you 72installed Django via ``python setup.py``. If it's not on your path, you can find 73it in ``site-packages/django/bin``, where ```site-packages``` is a directory 74within your Python installation. Consider symlinking to :doc:`django-admin.py 75</ref/django-admin>` from some place on your path, such as 76:file:`/usr/local/bin`. 77 78.. admonition:: Where should this code live? 79 80 If your background is in PHP, you're probably used to putting code under the 81 Web server's document root (in a place such as ``/var/www``). With Django, 82 you don't do that. It's not a good idea to put any of this Python code 83 within your Web server's document root, because it risks the possibility 84 that people may be able to view your code over the Web. That's not good for 85 security. 86 87 Put your code in some directory **outside** of the document root, such as 88 :file:`/home/mycode`. 89 90Let's look at what :djadmin:`startproject` created:: 91 92 mysite/ 93 __init__.py 94 manage.py 95 settings.py 96 urls.py 97 98These files are: 99 100 * :file:`__init__.py`: An empty file that tells Python that this directory 101 should be considered a Python package. (Read `more about packages`_ in the 102 official Python docs if you're a Python beginner.) 103 104 * :file:`manage.py`: A command-line utility that lets you interact with this 105 Django project in various ways. You can read all the details about 106 :file:`manage.py` in :doc:`/ref/django-admin`. 107 108 * :file:`settings.py`: Settings/configuration for this Django project. 109 :doc:`/topics/settings` will tell you all about how settings work. 110 111 * :file:`urls.py`: The URL declarations for this Django project; a "table of 112 contents" of your Django-powered site. You can read more about URLs in 113 :doc:`/topics/http/urls`. 114 115.. _more about packages: http://docs.python.org/tutorial/modules.html#packages 116 117The development server 118---------------------- 119 120Let's verify this worked. Change into the :file:`mysite` directory, if you 121haven't already, and run the command ``python manage.py runserver``. You'll see 122the following output on the command line:: 123 124 Validating models... 125 0 errors found. 126 127 Django version 1.0, using settings 'mysite.settings' 128 Development server is running at http://127.0.0.1:8000/ 129 Quit the server with CONTROL-C. 130 131You've started the Django development server, a lightweight Web server written 132purely in Python. We've included this with Django so you can develop things 133rapidly, without having to deal with configuring a production server -- such as 134Apache -- until you're ready for production. 135 136Now's a good time to note: DON'T use this server in anything resembling a 137production environment. It's intended only for use while developing. (We're in 138the business of making Web frameworks, not Web servers.) 139 140Now that the server's running, visit http://127.0.0.1:8000/ with your Web 141browser. You'll see a "Welcome to Django" page, in pleasant, light-blue pastel. 142It worked! 143 144.. admonition:: Changing the port 145 146 By default, the :djadmin:`runserver` command starts the development server 147 on the internal IP at port 8000. 148 149 If you want to change the server's port, pass 150 it as a command-line argument. For instance, this command starts the server 151 on port 8080: 152 153 .. code-block:: bash 154 155 python manage.py runserver 8080 156 157 If you want to change the server's IP, pass it along with the port. So to 158 listen on all public IPs (useful if you want to show off your work on other 159 computers), use: 160 161 .. code-block:: bash 162 163 python manage.py runserver 0.0.0.0:8000 164 165 Full docs for the development server can be found in the 166 :djadmin:`runserver` reference. 167 168Database setup 169-------------- 170 171Now, edit :file:`settings.py`. It's a normal Python module with 172module-level variables representing Django settings. Change the 173following keys in the :setting:`DATABASES` ``'default'`` item to match 174your databases connection settings. 175 176 * :setting:`ENGINE <DATABASE-ENGINE>` -- Either 177 ``'django.db.backends.postgresql_psycopg2'``, 178 ``'django.db.backends.mysql'`` or 179 ``'django.db.backends.sqlite3'``. Other backends are 180 :setting:`also available <DATABASE-ENGINE>`. 181 182 * :setting:`NAME` -- The name of your database. If you're using 183 SQLite, the database will be a file on your computer; in that 184 case, :setting:`NAME` should be the full absolute path, 185 including filename, of that file. If the file doesn't exist, it 186 will automatically be created when you synchronize the database 187 for the first time (see below). 188 189 When specifying the path, always use forward slashes, even on 190 Windows (e.g. ``C:/homes/user/mysite/sqlite3.db``). 191 192 * :setting:`USER` -- Your database username (not used for SQLite). 193 194 * :setting:`PASSWORD` -- Your database password (not used for 195 SQLite). 196 197 * :setting:`HOST` -- The host your database is on. Leave this as 198 an empty string if your database server is on the same physical 199 machine (not used for SQLite). 200 201If you're new to databases, we recommend simply using SQLite (by 202setting :setting:`ENGINE` to ``'django.db.backends.sqlite3'``). SQLite 203is included as part of Python 2.5 and later, so you won't need to 204install anything else. 205 206.. note:: 207 208 If you're using PostgreSQL or MySQL, make sure you've created a database by 209 this point. Do that with "``CREATE DATABASE database_name;``" within your 210 database's interactive prompt. 211 212 If you're using SQLite, you don't need to create anything beforehand - the 213 database file will be created automatically when it is needed. 214 215While you're editing :file:`settings.py`, take note of the 216:setting:`INSTALLED_APPS` setting towards the bottom of the file. That variable 217holds the names of all Django applications that are activated in this Django 218instance. Apps can be used in multiple projects, and you can package and 219distribute them for use by others in their projects. 220 221By default, :setting:`INSTALLED_APPS` contains the following apps, all of which 222come with Django: 223 224 * :mod:`django.contrib.auth` -- An authentication system. 225 226 * :mod:`django.contrib.contenttypes` -- A framework for content types. 227 228 * :mod:`django.contrib.sessions` -- A session framework. 229 230 * :mod:`django.contrib.sites` -- A framework for managing multiple sites 231 with one Django installation. 232 233 * :mod:`django.contrib.messages` -- A messaging framework. 234 235 * :mod:`django.contrib.staticfiles` -- A framework for managing 236 static files. 237 238These applications are included by default as a convenience for the common case. 239 240Each of these applications makes use of at least one database table, though, 241so we need to create the tables in the database before we can use them. To do 242that, run the following command: 243 244.. code-block:: bash 245 246 python manage.py syncdb 247 248The :djadmin:`syncdb` command looks at the :setting:`INSTALLED_APPS` setting and 249creates any necessary database tables according to the database settings in your 250:file:`settings.py` file. You'll see a message for each database table it 251creates, and you'll get a prompt asking you if you'd like to create a superuser 252account for the authentication system. Go ahead and do that. 253 254If you're interested, run the command-line client for your database and type 255``\dt`` (PostgreSQL), ``SHOW TABLES;`` (MySQL), or ``.schema`` (SQLite) to 256display the tables Django created. 257 258.. admonition:: For the minimalists 259 260 Like we said above, the default applications are included for the common 261 case, but not everybody needs them. If you don't need any or all of them, 262 feel free to comment-out or delete the appropriate line(s) from 263 :setting:`INSTALLED_APPS` before running :djadmin:`syncdb`. The 264 :djadmin:`syncdb` command will only create tables for apps in 265 :setting:`INSTALLED_APPS`. 266 267.. _creating-models: 268 269Creating models 270=============== 271 272Now that your environment -- a "project" -- is set up, you're set to start 273doing work. 274 275Each application you write in Django consists of a Python package, somewhere 276on your `Python path`_, that follows a certain convention. Django comes with a 277utility that automatically generates the basic directory structure of an app, 278so you can focus on writing code rather than creating directories. 279 280.. admonition:: Projects vs. apps 281 282 What's the difference between a project and an app? An app is a Web 283 application that does something -- e.g., a Weblog system, a database of 284 public records or a simple poll app. A project is a collection of 285 configuration and apps for a particular Web site. A project can contain 286 multiple apps. An app can be in multiple projects. 287 288Your apps can live anywhere on your `Python path`_. In this tutorial, we'll 289create our poll app in the :file:`mysite` directory for simplicity. 290 291To create your app, make sure you're in the :file:`mysite` directory and type 292this command: 293 294.. code-block:: bash 295 296 python manage.py startapp polls 297 298That'll create a directory :file:`polls`, which is laid out like this:: 299 300 polls/ 301 __init__.py 302 models.py 303 tests.py 304 views.py 305 306This directory structure will house the poll application. 307 308The first step in writing a database Web app in Django is to define your models 309-- essentially, your database layout, with additional metadata. 310 311.. admonition:: Philosophy 312 313 A model is the single, definitive source of data about your data. It contains 314 the essential fields and behaviors of the data you're storing. Django follows 315 the :ref:`DRY Principle <dry>`. The goal is to define your data model in one 316 place and automatically derive things from it. 317 318In our simple poll app, we'll create two models: polls and choices. A poll has 319a question and a publication date. A choice has two fields: the text of the 320choice and a vote tally. Each choice is associated with a poll. 321 322These concepts are represented by simple Python classes. Edit the 323:file:`polls/models.py` file so it looks like this:: 324 325 from django.db import models 326 327 class Poll(models.Model): 328 question = models.CharField(max_length=200) 329 pub_date = models.DateTimeField('date published') 330 331 class Choice(models.Model): 332 poll = models.ForeignKey(Poll) 333 choice = models.CharField(max_length=200) 334 votes = models.IntegerField() 335 336The code is straightforward. Each model is represented by a class that 337subclasses :class:`django.db.models.Model`. Each model has a number of class 338variables, each of which represents a database field in the model. 339 340Each field is represented by an instance of a :class:`~django.db.models.Field` 341class -- e.g., :class:`~django.db.models.CharField` for character fields and 342:class:`~django.db.models.DateTimeField` for datetimes. This tells Django what 343type of data each field holds. 344 345The name of each :class:`~django.db.models.Field` instance (e.g. ``question`` or 346``pub_date`` ) is the field's name, in machine-friendly format. You'll use this 347value in your Python code, and your database will use it as the column name. 348 349You can use an optional first positional argument to a 350:class:`~django.db.models.Field` to designate a human-readable name. That's used 351in a couple of introspective parts of Django, and it doubles as documentation. 352If this field isn't provided, Django will use the machine-readable name. In this 353example, we've only defined a human-readable name for ``Poll.pub_date``. For all 354other fields in this model, the field's machine-readable name will suffice as 355its human-readable name. 356 357Some :class:`~django.db.models.Field` classes have required elements. 358:class:`~django.db.models.CharField`, for example, requires that you give it a 359:attr:`~django.db.models.Field.max_length`. That's used not only in the database 360schema, but in validation, as we'll soon see. 361 362Finally, note a relationship is defined, using 363:class:`~django.db.models.ForeignKey`. That tells Django each Choice is related 364to a single Poll. Django supports all the common database relationships: 365many-to-ones, many-to-manys and one-to-ones. 366 367.. _`Python path`: http://docs.python.org/tutorial/modules.html#the-module-search-path 368 369Activating models 370================= 371 372That small bit of model code gives Django a lot of information. With it, Django 373is able to: 374 375 * Create a database schema (``CREATE TABLE`` statements) for this app. 376 * Create a Python database-access API for accessing Poll and Choice objects. 377 378But first we need to tell our project that the ``polls`` app is installed. 379 380.. admonition:: Philosophy 381 382 Django apps are "pluggable": You can use an app in multiple projects, and 383 you can distribute apps, because they don't have to be tied to a given 384 Django installation. 385 386Edit the :file:`settings.py` file again, and change the 387:setting:`INSTALLED_APPS` setting to include the string ``'polls'``. So 388it'll look like this:: 389 390 INSTALLED_APPS = ( 391 'django.contrib.auth', 392 'django.contrib.contenttypes', 393 'django.contrib.sessions', 394 'django.contrib.sites', 395 'polls' 396 ) 397 398Now Django knows to include the ``polls`` app. Let's run another 399command: 400 401.. code-block:: bash 402 403 python manage.py sql polls 404 405You should see something similar to the following (the ``CREATE TABLE`` SQL 406statements for the polls app): 407 408.. code-block:: sql 409 410 BEGIN; 411 CREATE TABLE "polls_poll" ( 412 "id" serial NOT NULL PRIMARY KEY, 413 "question" varchar(200) NOT NULL, 414 "pub_date" timestamp with time zone NOT NULL 415 ); 416 CREATE TABLE "polls_choice" ( 417 "id" serial NOT NULL PRIMARY KEY, 418 "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"), 419 "choice" varchar(200) NOT NULL, 420 "votes" integer NOT NULL 421 ); 422 COMMIT; 423 424Note the following: 425 426 * The exact output will vary depending on the database you are using. 427 428 * Table names are automatically generated by combining the name of the app 429 (``polls``) and the lowercase name of the model -- ``poll`` and 430 ``choice``. (You can override this behavior.) 431 432 * Primary keys (IDs) are added automatically. (You can override this, too.) 433 434 * By convention, Django appends ``"_id"`` to the foreign key field name. 435 Yes, you can override this, as well. 436 437 * The foreign key relationship is made explicit by a ``REFERENCES`` 438 statement. 439 440 * It's tailored to the database you're using, so database-specific field 441 types such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or 442 ``integer primary key`` (SQLite) are handled for you automatically. Same 443 goes for quoting of field names -- e.g., using double quotes or single 444 quotes. The author of this tutorial runs PostgreSQL, so the example 445 output is in PostgreSQL syntax. 446 447 * The :djadmin:`sql` command doesn't actually run the SQL in your database - 448 it just prints it to the screen so that you can see what SQL Django thinks 449 is required. If you wanted to, you could copy and paste this SQL into your 450 database prompt. However, as we will see shortly, Django provides an 451 easier way of committing the SQL to the database. 452 453If you're interested, also run the following commands: 454 455 * :djadmin:`python manage.py validate <validate>` -- Checks for any errors 456 in the construction of your models. 457 458 * :djadmin:`python manage.py sqlcustom polls <sqlcustom>` -- Outputs any 459 :ref:`custom SQL statements <initial-sql>` (such as table modifications or 460 constraints) that are defined for the application. 461 462 * :djadmin:`python manage.py sqlclear polls <sqlclear>` -- Outputs the 463 necessary ``DROP TABLE`` statements for this app, according to which 464 tables already exist in your database (if any). 465 466 * :djadmin:`python manage.py sqlindexes polls <sqlindexes>` -- Outputs the 467 ``CREATE INDEX`` statements for this app. 468 469 * :djadmin:`python manage.py sqlall polls <sqlall>` -- A combination of all 470 the SQL from the :djadmin:`sql`, :djadmin:`sqlcustom`, and 471 :djadmin:`sqlindexes` commands. 472 473Looking at the output of those commands can help you understand what's actually 474happening under the hood. 475 476Now, run :djadmin:`syncdb` again to create those model tables in your database: 477 478.. code-block:: bash 479 480 python manage.py syncdb 481 482The :djadmin:`syncdb` command runs the sql from 'sqlall' on your database for 483all apps in :setting:`INSTALLED_APPS` that don't already exist in your database. 484This creates all the tables, initial data and indexes for any apps you have 485added to your project since the last time you ran syncdb. :djadmin:`syncdb` can 486be called as often as you like, and it will only ever create the tables that 487don't exist. 488 489Read the :doc:`django-admin.py documentation </ref/django-admin>` for full 490information on what the ``manage.py`` utility can do. 491 492Playing with the API 493==================== 494 495Now, let's hop into the interactive Python shell and play around with the free 496API Django gives you. To invoke the Python shell, use this command: 497 498.. code-block:: bash 499 500 python manage.py shell 501 502We're using this instead of simply typing "python", because ``manage.py`` sets 503up the project's environment for you. "Setting up the environment" involves two 504things: 505 506 * Putting ``polls`` on ``sys.path``. For flexibility, several pieces of 507 Django refer to projects in Python dotted-path notation (e.g. 508 ``'polls.models'``). In order for this to work, the ``polls`` 509 package has to be on ``sys.path``. 510 511 We've already seen one example of this: the :setting:`INSTALLED_APPS` 512 setting is a list of packages in dotted-path notation. 513 514 * Setting the ``DJANGO_SETTINGS_MODULE`` environment variable, which gives 515 Django the path to your ``settings.py`` file. 516 517.. admonition:: Bypassing manage.py 518 519 If you'd rather not use ``manage.py``, no problem. Just make sure ``mysite`` 520 and ``polls`` are at the root level on the Python path (i.e., ``import mysite`` 521 and ``import polls`` work) and set the ``DJANGO_SETTINGS_MODULE`` environment 522 variable to ``mysite.settings``. 523 524 For more information on all of this, see the :doc:`django-admin.py 525 documentation </ref/django-admin>`. 526 527Once you're in the shell, explore the :doc:`database API </topics/db/queries>`:: 528 529 >>> from polls.models import Poll, Choice # Import the model classes we just wrote. 530 531 # No polls are in the system yet. 532 >>> Poll.objects.all() 533 [] 534 535 # Create a new Poll. 536 >>> import datetime 537 >>> p = Poll(question="What's up?", pub_date=datetime.datetime.now()) 538 539 # Save the object into the database. You have to call save() explicitly. 540 >>> p.save() 541 542 # Now it has an ID. Note that this might say "1L" instead of "1", depending 543 # on which database you're using. That's no biggie; it just means your 544 # database backend prefers to return integers as Python long integer 545 # objects. 546 >>> p.id 547 1 548 549 # Access database columns via Python attributes. 550 >>> p.question 551 "What's up?" 552 >>> p.pub_date 553 datetime.datetime(2007, 7, 15, 12, 00, 53) 554 555 # Change values by changing the attributes, then calling save(). 556 >>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0) 557 >>> p.save() 558 559 # objects.all() displays all the polls in the database. 560 >>> Poll.objects.all() 561 [<Poll: Poll object>] 562 563 564Wait a minute. ``<Poll: Poll object>`` is, utterly, an unhelpful representation 565of this object. Let's fix that by editing the polls model (in the 566``polls/models.py`` file) and adding a 567:meth:`~django.db.models.Model.__unicode__` method to both ``Poll`` and 568``Choice``:: 569 570 class Poll(models.Model): 571 # ... 572 def __unicode__(self): 573 return self.question 574 575 class Choice(models.Model): 576 # ... 577 def __unicode__(self): 578 return self.choice 579 580It's important to add :meth:`~django.db.models.Model.__unicode__` methods to 581your models, not only for your own sanity when dealing with the interactive 582prompt, but also because objects' representations are used throughout Django's 583automatically-generated admin. 584 585.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not 586 :meth:`~django.db.models.Model.__str__`? 587 588 If you're familiar with Python, you might be in the habit of adding 589 :meth:`~django.db.models.Model.__str__` methods to your classes, not 590 :meth:`~django.db.models.Model.__unicode__` methods. We use 591 :meth:`~django.db.models.Model.__unicode__` here because Django models deal 592 with Unicode by default. All data stored in your database is converted to 593 Unicode when it's returned. 594 595 Django models have a default :meth:`~django.db.models.Model.__str__` method 596 that calls :meth:`~django.db.models.Model.__unicode__` and converts the 597 result to a UTF-8 bytestring. This means that ``unicode(p)`` will return a 598 Unicode string, and ``str(p)`` will return a normal string, with characters 599 encoded as UTF-8. 600 601 If all of this is gibberish to you, just remember to add 602 :meth:`~django.db.models.Model.__unicode__` methods to your models. With any 603 luck, things should Just Work for you. 604 605Note these are normal Python methods. Let's add a custom method, just for 606demonstration:: 607 608 import datetime 609 # ... 610 class Poll(models.Model): 611 # ... 612 def was_published_today(self): 613 return self.pub_date.date() == datetime.date.today() 614 615Note the addition of ``import datetime`` to reference Python's standard 616``datetime`` module. 617 618Save these changes and start a new Python interactive shell by running 619``python manage.py shell`` again:: 620 621 >>> from polls.models import Poll, Choice 622 623 # Make sure our __unicode__() addition worked. 624 >>> Poll.objects.all() 625 [<Poll: What's up?>] 626 627 # Django provides a rich database lookup API that's entirely driven by 628 # keyword arguments. 629 >>> Poll.objects.filter(id=1) 630 [<Poll: What's up?>] 631 >>> Poll.objects.filter(question__startswith='What') 632 [<Poll: What's up?>] 633 634 # Get the poll whose year is 2007. 635 >>> Poll.objects.get(pub_date__year=2007) 636 <Poll: What's up?> 637 638 >>> Poll.objects.get(id=2) 639 Traceback (most recent call last): 640 ... 641 DoesNotExist: Poll matching query does not exist. 642 643 # Lookup by a primary key is the most common case, so Django provides a 644 # shortcut for primary-key exact lookups. 645 # The following is identical to Poll.objects.get(id=1). 646 >>> Poll.objects.get(pk=1) 647 <Poll: What's up?> 648 649 # Make sure our custom method worked. 650 >>> p = Poll.objects.get(pk=1) 651 >>> p.was_published_today() 652 False 653 654 # Give the Poll a couple of Choices. The create call constructs a new 655 # choice object, does the INSERT statement, adds the choice to the set 656 # of available choices and returns the new Choice object. Django creates 657 # a set to hold the "other side" of a ForeignKey relation 658 # (e.g. a poll's choices) which can be accessed via the API. 659 >>> p = Poll.objects.get(pk=1) 660 661 # Display any choices from the related object set -- none so far. 662 >>> p.choice_set.all() 663 [] 664 665 # Create three choices. 666 >>> p.choice_set.create(choice='Not much', votes=0) 667 <Choice: Not much> 668 >>> p.choice_set.create(choice='The sky', votes=0) 669 <Choice: The sky> 670 >>> c = p.choice_set.create(choice='Just hacking again', votes=0) 671 672 # Choice objects have API access to their related Poll objects. 673 >>> c.poll 674 <Poll: What's up?> 675 676 # And vice versa: Poll objects get access to Choice objects. 677 >>> p.choice_set.all() 678 [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>] 679 >>> p.choice_set.count() 680 3 681 682 # The API automatically follows relationships as far as you need. 683 # Use double underscores to separate relationships. 684 # This works as many levels deep as you want; there's no limit. 685 # Find all Choices for any poll whose pub_date is in 2007. 686 >>> Choice.objects.filter(poll__pub_date__year=2007) 687 [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>] 688 689 # Let's delete one of the choices. Use delete() for that. 690 >>> c = p.choice_set.filter(choice__startswith='Just hacking') 691 >>> c.delete() 692 693For more information on model relations, see :doc:`Accessing related objects 694</ref/models/relations>`. For more on how to use double underscores to perform 695field lookups via the API, see `Field lookups`__. For full details on the 696database API, see our :doc:`Database API reference </topics/db/queries>`. 697 698__ http://docs.djangoproject.com/en/1.2/topics/db/queries/#field-lookups 699 700When you're comfortable with the API, read :doc:`part 2 of this tutorial 701</intro/tutorial02>` to get Django's automatic admin working.