Code

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

File magic-tutorial01-and-rst-title-fix.patch, 12.9 KB (added by jdunck@…, 8 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