Ticket #1464: magic-tutorial01-and-rst-title-fix.patch

File magic-tutorial01-and-rst-title-fix.patch, 12.9 KB (added by jdunck@…, 9 years ago)

Updates tutorial01 and fixes a couple title issues on other docs.

  • tutorial01.txt

     
    127127Run the following command to initialize your database with Django's core
    128128database tables::
    129129
    130     python manage.py init
    131 
     130    python manage.py syncdb
     131   
    132132If you don't see any errors, it worked.
    133133
    134134If you're interested, run the command-line client for your database and type
     
    137137
    138138.. admonition:: About those database tables
    139139
    140     The tables created by ``manage.py init`` are for sessions, authentication
    141     and other features Django provides. The next release of Django will have
    142     a "lite" version of the ``init`` command that won't install any database
    143     tables if you don't want them.
     140    At this point, the tables created by ``manage.py syncdb`` are for sessions, authentication
     141    and other features Django provides.
    144142
    145143Creating models
    146144===============
     
    176174
    177175    polls/
    178176        __init__.py
    179         models/
    180             __init__.py
    181             polls.py
     177        models.py
    182178        views.py
    183179
    184180This directory structure will house the poll application.
     
    198194choice and a vote tally. Each choice is associated with a poll.
    199195
    200196These concepts are represented by simple Python classes. Edit the
    201 ``polls/models/polls.py`` file so it looks like this::
     197``polls/models.py`` file so it looks like this::
    202198
    203     from django.core import meta
     199    from django.db import models
    204200
    205     class Poll(meta.Model):
    206         question = meta.CharField(maxlength=200)
    207         pub_date = meta.DateTimeField('date published')
     201    class Poll(models.Model):
     202        question = models.CharField(maxlength=200)
     203        pub_date = models.DateTimeField('date published')
    208204
    209     class Choice(meta.Model):
    210         poll = meta.ForeignKey(Poll)
    211         choice = meta.CharField(maxlength=200)
    212         votes = meta.IntegerField()
     205    class Choice(models.Model):
     206        poll = models.ForeignKey(Poll)
     207        choice = models.CharField(maxlength=200)
     208        votes = models.IntegerField()
    213209
    214210The code is straightforward. Each model is represented by a class that
    215 subclasses ``django.core.meta.Model``. Each model has a number of class
     211subclasses ``django.db.models.Model``. Each model has a number of class
    216212variables, each of which represents a database field in the model.
    217213
    218 Each field is represented by an instance of a ``meta.*Field`` class -- e.g.,
    219 ``meta.CharField`` for character fields and ``meta.DateTimeField`` for
     214Each field is represented by an instance of a ``models.*Field`` class -- e.g.,
     215``models.CharField`` for character fields and ``models.DateTimeField`` for
    220216datetimes. This tells Django what type of data each field holds.
    221217
    222 The name of each ``meta.*Field`` instance (e.g. ``question`` or ``pub_date`` )
     218The name of each ``models.*Field`` instance (e.g. ``question`` or ``pub_date`` )
    223219is the field's name, in machine-friendly format. You'll use this value in your
    224220Python code, and your database will use it as the column name.
    225221
     
    230226name for ``Poll.pub_date``. For all other fields in this model, the field's
    231227machine-readable name will suffice as its human-readable name.
    232228
    233 Some ``meta.*Field`` classes have required elements. ``meta.CharField``, for
     229Some ``models.*Field`` classes have required elements. ``models.CharField``, for
    234230example, requires that you give it a ``maxlength``. That's used not only in the
    235231database schema, but in validation, as we'll soon see.
    236232
    237 Finally, note a relationship is defined, using ``meta.ForeignKey``. That tells
     233Finally, note a relationship is defined, using ``models.ForeignKey``. That tells
    238234Django each Choice is related to a single Poll. Django supports all the common
    239235database relationships: many-to-ones, many-to-manys and one-to-ones.
    240236
     
    275271You should see the following (the CREATE TABLE SQL statements for the polls app)::
    276272
    277273    BEGIN;
    278     CREATE TABLE "polls_polls" (
     274    CREATE TABLE "polls_poll" (
    279275        "id" serial NOT NULL PRIMARY KEY,
    280276        "question" varchar(200) NOT NULL,
    281277        "pub_date" timestamp with time zone NOT NULL
    282278    );
    283     CREATE TABLE "polls_choices" (
     279    CREATE TABLE "polls_choice" (
    284280        "id" serial NOT NULL PRIMARY KEY,
    285281        "poll_id" integer NOT NULL REFERENCES "polls_polls" ("id"),
    286282        "choice" varchar(200) NOT NULL,
     
    291287Note the following:
    292288
    293289    * Table names are automatically generated by combining the name of the app
    294       (``polls``) with a plural version of the object name (polls and choices).
     290      (``polls``) and the name of the models (poll and choice).
    295291      (You can override this behavior.)
    296292
    297293    * Primary keys (IDs) are added automatically. (You can override this, too.)
    298294
    299     * Django appends ``"_id"`` to the foreign key field name, by convention.
     295    * By convention, Django appends ``"_id"`` to the foreign key field name.
    300296      Yes, you can override this, as well.
    301297
    302298    * The foreign key relationship is made explicit by a ``REFERENCES`` statement.
     
    306302      ``integer primary key`` (SQLite) are handled for you automatically. Same
    307303      goes for quoting of field names -- e.g., using double quotes or single
    308304      quotes. The author of this tutorial runs PostgreSQL, so the example
    309       output is inPostgreSQL syntax.
     305      output is in PostgreSQL syntax.
    310306
    311307If you're interested, also run the following commands:
    312308
    313     * ``python manage.py sqlinitialdata polls`` -- Outputs the initial-data
    314       inserts required for Django's admin framework.
     309    * ``python manage.py sqlinitialdata polls`` -- Outputs any initial data
     310      required for Django's admin framework and your models.
    315311
    316312    * ``python manage.py sqlclear polls`` -- Outputs the necessary ``DROP
    317313      TABLE`` statements for this app, according to which tables already exist
     
    326322Looking at the output of those commands can help you understand what's actually
    327323happening under the hood.
    328324
    329 Now, run this command to create the database tables for the polls app
    330 automatically::
     325Now, run ``syncdb`` again to create the model tables in your database::
    331326
    332     python manage.py install polls
     327    python manage.py syncdb
    333328
    334 Behind the scenes, all that command does is take the output of
    335 ``python manage.py sqlall polls`` and execute it in the database pointed-to by
    336 your Django settings file.
     329In addition to initializing Django's core tables, ``syncdb`` inspects the apps listed in INSTALLED_APPS, and, for each new app, executes the output of the respective ``python manage.py sqlall`` command against your database.
    337330
    338331Read the `django-admin.py documentation`_ for full information on what the
    339332``manage.py`` utility can do.
     
    376369
    377370    # Modules are dynamically created within django.models.
    378371    # Their names are plural versions of the model class names.
    379     >>> from django.models.polls import polls, choices
     372    >>> from myproject.polls import Poll, Choice
    380373
    381374    # No polls are in the system yet.
    382     >>> polls.get_list()
     375    >>> polls.objects.all()
    383376    []
    384377
    385378    # Create a new Poll.
    386379    >>> from datetime import datetime
    387     >>> p = polls.Poll(question="What's up?", pub_date=datetime.now())
     380    >>> p = Poll(question="What's up?", pub_date=datetime.now())
    388381
    389382    # Save the object into the database. You have to call save() explicitly.
    390383    >>> p.save()
     
    407400    >>> p.save()
    408401
    409402    # get_list() displays all the polls in the database.
    410     >>> polls.get_list()
     403    >>> Poll.objects.all()
    411404    [<Poll object>]
    412405
     406
    413407Wait a minute. ``<Poll object>`` is, utterly, an unhelpful representation of
    414408this object. Let's fix that by editing the polls model
    415 (in the ``polls/models/polls.py`` file) and adding a ``__repr__()`` method to
     409(in the ``polls/models.py`` file) and adding a ``__repr__()`` method to
    416410both ``Poll`` and ``Choice``::
    417411
    418     class Poll(meta.Model):
     412    class Poll(models.Model):
    419413        # ...
    420414        def __repr__(self):
    421415            return self.question
    422416
    423     class Choice(meta.Model):
     417    class Choice(models.Model):
    424418        # ...
    425419        def __repr__(self):
    426420            return self.choice
     
    432426Note these are normal Python methods. Let's add a custom method, just for
    433427demonstration::
    434428
    435     class Poll(meta.Model):
     429    class Poll(models.Model):
    436430        # ...
    437431        def was_published_today(self):
    438432            return self.pub_date.date() == datetime.date.today()
    439433
    440 Note ``import datetime`` wasn't necessary. Each model method has access to
    441 a handful of commonly-used variables for convenience, including the
    442 ``datetime`` module from the Python standard library.
     434Note the addition of ``import datetime`` to reference Python's standard datetime module.
    443435
    444436Let's jump back into the Python interactive shell by running
    445437``python manage.py shell`` again::
    446438
    447     >>> from django.models.polls import polls, choices
     439    >>> from polls.models import Poll, Choice
    448440    # Make sure our __repr__() addition worked.
    449     >>> polls.get_list()
     441    >>> polls.objects.all()
    450442    [What's up?]
    451443
    452444    # Django provides a rich database lookup API that's entirely driven by
    453445    # keyword arguments.
    454     >>> polls.get_object(id__exact=1)
    455     What's up?
    456     >>> polls.get_object(question__startswith='What')
    457     What's up?
     446    >>> Poll.objects.filter(id__exact=1)
     447    [What's up?]
     448    >>> Poll.objects.filter(question__startswith='What')
     449    [What's up?]
    458450
    459451    # Get the poll whose year is 2005. Of course, if you're going through this
    460452    # tutorial in another year, change as appropriate.
    461     >>> polls.get_object(pub_date__year=2005)
     453    >>> Poll.objects.get(pub_date__year=2005)
    462454    What's up?
    463455
    464     >>> polls.get_object(id__exact=2)
     456    >>> Poll.objects.get(id__exact=2)
    465457    Traceback (most recent call last):
    466458        ...
    467     PollDoesNotExist: Poll does not exist for {'id__exact': 2}
    468     >>> polls.get_list(question__startswith='What')
     459    DoesNotExist: Poll does not exist for {'id__exact': 2}
     460    >>> Poll.objects.filter(question__startswith='What')
    469461    [What's up?]
    470462
    471463    # Lookup by a primary key is the most common case, so Django provides a
    472464    # shortcut for primary-key exact lookups.
    473     # The following is identical to polls.get_object(id__exact=1).
    474     >>> polls.get_object(pk=1)
     465    # The following is identical to Poll.objects.get(id__exact=1).
     466    >>> Poll.objects.get(pk=1)
    475467    What's up?
    476468
    477469    # Make sure our custom method worked.
    478     >>> p = polls.get_object(pk=1)
     470    >>> p = Poll.objects.get(pk=1)
    479471    >>> p.was_published_today()
    480472    False
    481473
    482474    # Give the Poll a couple of Choices. Each one of these method calls does an
    483475    # INSERT statement behind the scenes and returns the new Choice object.
    484     >>> p = polls.get_object(pk=1)
    485     >>> p.add_choice(choice='Not much', votes=0)
     476    >>> p = Poll.objects.get(pk=1)
     477    >>> p.choice_set.add(choice='Not much', votes=0)
    486478    Not much
    487     >>> p.add_choice(choice='The sky', votes=0)
     479    >>> p.choice_set.add(choice='The sky', votes=0)
    488480    The sky
    489     >>> c = p.add_choice(choice='Just hacking again', votes=0)
     481    >>> c = p.choice_set.add(choice='Just hacking again', votes=0)
    490482
    491483    # Choice objects have API access to their related Poll objects.
    492     >>> c.get_poll()
     484    >>> c.poll
    493485    What's up?
    494486
    495487    # And vice versa: Poll objects get access to Choice objects.
    496     >>> p.get_choice_list()
     488    >>> p.choice_set.all()
    497489    [Not much, The sky, Just hacking again]
    498     >>> p.get_choice_count()
     490    >>> p.choice_set.all().count()
    499491    3
    500492
    501493    # The API automatically follows relationships as far as you need.
    502494    # Use double underscores to separate relationships.
    503495    # This works as many levels deep as you want. There's no limit.
    504496    # Find all Choices for any poll whose pub_date is in 2005.
    505     >>> choices.get_list(poll__pub_date__year=2005)
     497    >>> Choice.objects.filter(poll__pub_date__year=2005)
    506498    [Not much, The sky, Just hacking again]
    507499
    508500    # Let's delete one of the choices. Use delete() for that.
    509     >>> c = p.get_choice(choice__startswith='Just hacking')
     501    >>> c = p.choice_set.filter(choice__startswith='Just hacking')
    510502    >>> c.delete()
    511503
    512504For full details on the database API, see our `Database API reference`_.
  • middleware.txt

     
    9696``Date`` and ``Content-Length`` response-headers.
    9797
    9898django.contrib.sessions.middleware.SessionMiddleware
    99 --------------------------------------------
     99----------------------------------------------------
    100100
    101101Enables session support. See the `session documentation`_.
    102102
  • templates_python.txt

     
    256256you'll see below.
    257257
    258258Subclassing Context: RequestContext
    259 ----------------------------------
     259-----------------------------------
    260260
    261261Django comes with a special ``Context`` class,
    262262``django.template.RequestContext``, that acts slightly differently than
Back to Top