Assumed Python 3 throughout docs/intro.

Various small fixes while I was proof-reading.

docs/intro/contributing.txt

@@ -20,8 +20,8 @@ For this tutorial, we expect that you have at least a basic understanding of
 how Django works. This means you should be comfortable going through the
 existing tutorials on :doc:`writing your first Django app</intro/tutorial01>`.
 In addition, you should have a good understanding of Python itself. But if you
-don't, "Dive Into Python" (for `Python 2`__, for `Python 3`__) is a fantastic
+don't, `Dive Into Python`__ is a fantastic (and free) online book for
-(and free) online book for beginning Python programmers.
+beginning Python programmers.
 
 Those of you who are unfamiliar with version control systems and Trac will find
 that this tutorial and its links include just enough information to get started.
@@ -37,7 +37,6 @@ so that it can be of use to the widest audience.
     to |django-developers| or drop by `#django-dev on irc.freenode.net`__ to
     chat with other Django users who might be able to help.
 
-__ http://diveintopython.net/toc/index.html
 __ http://diveintopython3.net/
 __ irc://irc.freenode.net/django-dev
 

docs/intro/index.txt

@@ -29,14 +29,10 @@ place: read this material to quickly get up and running.
     `list of Python resources for non-programmers`_
 
     If you already know a few other languages and want to get up to speed with
-    Python quickly, we recommend "Dive Into Python" (for `Python 2`_, for
+    Python quickly, we recommend `Dive Into Python`_. If that's not quite your
-    `Python 3`_, also available in a
+    style, there are many other `books about Python`_.
-    `dead-tree version`_). If that's not quite your style, there are quite
-    a few other `books about Python`_.
 
     .. _python: http://python.org/
     .. _list of Python resources for non-programmers: https://wiki.python.org/moin/BeginnersGuide/NonProgrammers
-    .. _Python 2: http://diveintopython.net/
+    .. _Dive Into Python: http://diveintopython3.net/
-    .. _Python 3: http://diveintopython3.net/
-    .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
     .. _books about Python: https://wiki.python.org/moin/PythonBooks

docs/intro/install.txt

@@ -15,8 +15,8 @@ SQLite_ so you won't need to set up a database just yet.
 
 .. _sqlite: http://sqlite.org/
 
-Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
+Get the latest version of Python at http://www.python.org/download/ or with
-probably already have it installed.
+your operating system's package manager.
 
 .. admonition:: Django on Jython
 
@@ -28,8 +28,8 @@ probably already have it installed.
 You can verify that Python is installed by typing ``python`` from your shell;
 you should see something like::
 
-    Python 2.7.3 (default, Jan  2 2013, 13:56:14)
+    Python 3.3.3 (default, Nov 26 2013, 13:33:18)
-    [GCC 4.7.2] on linux2
+    [GCC 4.8.2] on linux
     Type "help", "copyright", "credits" or "license" for more information.
     >>>
 

docs/intro/overview.txt

@@ -22,7 +22,7 @@ code.
 .. _object-relational mapper: http://en.wikipedia.org/wiki/Object-relational_mapping
 
 The :doc:`data-model syntax </topics/db/models>` offers many rich ways of
-representing your models -- so far, it's been solving two years' worth of
+representing your models -- so far, it's been solving many years' worth of
 database-schema problems. Here's a quick example, which might be saved in
 the file ``mysite/news/models.py``::
 
@@ -31,8 +31,7 @@ the file ``mysite/news/models.py``::
     class Reporter(models.Model):
         full_name = models.CharField(max_length=70)
 
-        # On Python 3: def __str__(self):
+        def __str__(self):              # __unicode__ on Python 2
-        def __unicode__(self):
             return self.full_name
 
     class Article(models.Model):
@@ -41,8 +40,7 @@ the file ``mysite/news/models.py``::
         content = models.TextField()
         reporter = models.ForeignKey(Reporter)
 
-        # On Python 3: def __str__(self):
+        def __str__(self):              # __unicode__ on Python 2
-        def __unicode__(self):
             return self.headline
 
 Install it
@@ -127,7 +125,7 @@ necessary:
     # The API follows relationships as far as you need, performing efficient
     # JOINs for you behind the scenes.
     # This finds all articles by a reporter whose name starts with "John".
-    >>> Article.objects.filter(reporter__full_name__startswith="John")
+    >>> Article.objects.filter(reporter__full_name__startswith='John')
     [<Article: Django is cool>]
 
     # Change an object by altering its attributes and calling save().
@@ -224,11 +222,12 @@ Generally, a view retrieves data according to the parameters, loads a template
 and renders the template with the retrieved data. Here's an example view for
 ``year_archive`` from above::
 
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
 
     def year_archive(request, year):
         a_list = Article.objects.filter(pub_date__year=year)
-        return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list})
+        context = {'year': year, 'article_list': a_list}
+        return render(request, 'news/year_archive.html', context)
 
 This example uses Django's :doc:`template system </topics/templates>`, which has
 several powerful features but strives to stay simple enough for non-programmers
@@ -265,7 +264,7 @@ might look like:
 
 Variables are surrounded by double-curly braces. ``{{ article.headline }}``
 means "Output the value of the article's headline attribute." But dots aren't
-used only for attribute lookup: They also can do dictionary-key lookup, index
+used only for attribute lookup. They also can do dictionary-key lookup, index
 lookup and function calls.
 
 Note ``{{ article.pub_date|date:"F j, Y" }}`` uses a Unix-style "pipe" (the "|"
@@ -278,7 +277,7 @@ template filters <howto-writing-custom-template-filters>`. You can write
 :doc:`custom template tags </howto/custom-template-tags>`, which run custom
 Python code behind the scenes.
 
-Finally, Django uses the concept of "template inheritance": That's what the
+Finally, Django uses the concept of "template inheritance". That's what the
 ``{% extends "base.html" %}`` does. It means "First load the template called
 'base', which has defined a bunch of blocks, and fill the blocks with the
 following blocks." In short, that lets you dramatically cut down on redundancy
@@ -306,8 +305,8 @@ easy as changing a single file -- the base template.
 
 It also lets you create multiple versions of a site, with different base
 templates, while reusing child templates. Django's creators have used this
-technique to create strikingly different cell-phone editions of sites -- simply
+technique to create strikingly different mobile versions of sites -- simply by
-by creating a new base template.
+creating a new base template.
 
 Note that you don't have to use Django's template system if you prefer another
 system. While Django's template system is particularly well-integrated with

docs/intro/reusable-apps.txt

@@ -215,9 +215,10 @@ this. For a small app like polls, this process isn't too difficult.
                'License :: OSI Approved :: BSD License', # example license
                'Operating System :: OS Independent',
                'Programming Language :: Python',
-               # replace these appropriately if you are using Python 3
+               # Replace these appropriately if you are stuck on Python 2.
-               'Programming Language :: Python :: 2',
+               'Programming Language :: Python :: 3',
-               'Programming Language :: Python :: 2.7',
+               'Programming Language :: Python :: 3.2',
+               'Programming Language :: Python :: 3.3',
                'Topic :: Internet :: WWW/HTTP',
                'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
            ],

docs/intro/tutorial01.txt

@@ -22,13 +22,12 @@ tell Django is installed and which version by running the following command:
 If Django is installed, you should see the version of your installation. If it
 isn't, you'll get an error telling "No module named django".
 
-This tutorial is written for Django |version| and Python 2.x. If the Django
+This tutorial is written for Django |version| and Python 3.2 or later. If the
-version doesn't match, you can refer to the tutorial for your version of
+Django version doesn't match, you can refer to the tutorial for your version
-Django by using the version switcher at the bottom right corner of this page,
+of Django by using the version switcher at the bottom right corner of this
-or update Django to the newest version. If you are using Python 3.x, be aware
+page, or update Django to the newest version. If you are still using Python
-that your code may need to differ from what is in the tutorial and you should
+2.7, you will need to adjust the code samples slightly, as described in
-continue using the tutorial only if you know what you are doing with Python
+comments.
-3.x.
 
 See :doc:`How to install Django </topics/install>` for advice on how to remove
 older versions of Django and install a newer one.
@@ -154,7 +153,7 @@ purely in Python. We've included this with Django so you can develop things
 rapidly, without having to deal with configuring a production server -- such as
 Apache -- until you're ready for production.
 
-Now's a good time to note: **Don't** use this server in anything resembling a
+Now's a good time to note: **don't** use this server in anything resembling a
 production environment. It's intended only for use while developing. (We're in
 the business of making Web frameworks, not Web servers.)
 
@@ -190,9 +189,8 @@ It worked!
 
     The development server automatically reloads Python code for each request
     as needed. You don't need to restart the server for code changes to take
-    effect. However, some actions like adding files or compiling translation
+    effect. However, some actions like adding files don't trigger a restart,
-    files don't trigger a restart, so you'll have to restart the server in
+    so you'll have to restart the server in these cases.
-    these cases.
 
 Database setup
 --------------
@@ -214,8 +212,8 @@ settings:
   ``'django.db.backends.sqlite3'``,
   ``'django.db.backends.postgresql_psycopg2'``,
   ``'django.db.backends.mysql'``, or
-  ``'django.db.backends.oracle'``. Other backends are :setting:`also available
+  ``'django.db.backends.oracle'``. Other backends are :ref:`also available
-  <DATABASE-ENGINE>`.
+  <third-party-notes>`.
 
 * :setting:`NAME` -- The name of your database. If you're using SQLite, the
   database will be a file on your computer; in that case, :setting:`NAME`
@@ -654,9 +652,8 @@ Once you're in the shell, explore the :doc:`database API </topics/db/queries>`::
 Wait a minute. ``<Question: Question object>`` is, utterly, an unhelpful representation
 of this object. Let's fix that by editing the ``Question`` model (in the
 ``polls/models.py`` file) and adding a
-:meth:`~django.db.models.Model.__unicode__` method to both ``Question`` and
+:meth:`~django.db.models.Model.__str__` method to both ``Question`` and
-``Choice``. On Python 3, simply replace ``__unicode__`` by ``__str__`` in the
+``Choice``:
-following example:
 
 .. snippet::
     :filename: polls/models.py
@@ -665,42 +662,35 @@ following example:
 
     class Question(models.Model):
         # ...
-        def __unicode__(self):  # Python 3: def __str__(self):
+        def __str__(self):              # __unicode__ on Python 2
             return self.question_text
 
     class Choice(models.Model):
         # ...
-        def __unicode__(self):  # Python 3: def __str__(self):
+        def __str__(self):              # __unicode__ on Python 2
             return self.choice_text
 
-It's important to add :meth:`~django.db.models.Model.__unicode__` methods (or
+It's important to add :meth:`~django.db.models.Model.__str__` methods to your
-:meth:`~django.db.models.Model.__str__` on Python 3) to your models, not only
+models, not only for your own sanity when dealing with the interactive prompt,
-for your own sanity when dealing with the interactive prompt, but also because
+but also because objects' representations are used throughout Django's
-objects' representations are used throughout Django's automatically-generated
+automatically-generated admin.
-admin.
 
-.. admonition:: ``__unicode__`` or ``__str__``?
+.. admonition:: ``__str__`` or ``__unicode__``?
 
-    On Python 3, things are simpler, just use
+    On Python 3, it's easy, just use
-    :meth:`~django.db.models.Model.__str__` and forget about
+    :meth:`~django.db.models.Model.__str__`.
-    :meth:`~django.db.models.Model.__unicode__`.
 
-    If you're familiar with Python 2, you might be in the habit of adding
+    On Python 2, you should define :meth:`~django.db.models.Model.__unicode__`
-    :meth:`~django.db.models.Model.__str__` methods to your classes, not
+    methods returning ``unicode`` values instead. Django models have a default
-    :meth:`~django.db.models.Model.__unicode__` methods. We use
+    :meth:`~django.db.models.Model.__str__` method that calls
-    :meth:`~django.db.models.Model.__unicode__` here because Django models deal
+    :meth:`~django.db.models.Model.__unicode__` and converts the result to a
-    with Unicode by default. All data stored in your database is converted to
+    UTF-8 bytestring. This means that ``unicode(p)`` will return a Unicode
-    Unicode when it's returned.
+    string, and ``str(p)`` will return a bytestring, with characters encoded
+    as UTF-8. Python does the opposite: :class:`object` has a ``__unicode__``
+    method that calls ``__str__`` and interprets the result as an ASCII
+    bytestring. This difference can create confusion.
 
-    Django models have a default :meth:`~django.db.models.Model.__str__` method
+    If all of this is gibberish to you, just use Python 3.
-    that calls :meth:`~django.db.models.Model.__unicode__` and converts the
-    result to a UTF-8 bytestring. This means that ``unicode(p)`` will return a
-    Unicode string, and ``str(p)`` will return a normal string, with characters
-    encoded as UTF-8.
-
-    If all of this is gibberish to you, just remember to add
-    :meth:`~django.db.models.Model.__unicode__` methods to your models. With any
-    luck, things should Just Work for you.
 
 Note these are normal Python methods. Let's add a custom method, just for
 demonstration:

docs/topics/install.txt

@@ -10,8 +10,8 @@ Install Python
 Being a Python Web framework, Django requires Python. It works with Python 2.7,
 3.2 or 3.3.
 
-Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
+Get the latest version of Python at http://www.python.org/download/ or with
-probably already have it installed.
+your operating system's package manager.
 
 .. admonition:: Django on Jython