From 99649ddcb21b5c07258569d4585ffe3cf9eb4f38 Mon Sep 17 00:00:00 2001
From: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon, 30 Dec 2013 18:15:49 +0100
Subject: [PATCH] Assumed Python 3 throughout docs/intro.
Various small fixes while I was proof-reading.
---
docs/intro/contributing.txt | 5 +--
docs/intro/index.txt | 10 ++---
docs/intro/install.txt | 8 ++--
docs/intro/overview.txt | 23 ++++++-----
docs/intro/reusable-apps.txt | 7 ++--
docs/intro/tutorial01.txt | 74 ++++++++++++++++--------------------
docs/topics/install.txt | 4 +-
7 files changed, 58 insertions(+), 73 deletions(-)
diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt
index 8f41b71056..8a16a9b0d0 100644
--- a/docs/intro/contributing.txt
+++ b/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
-(and free) online book for beginning Python programmers.
+don't, `Dive Into Python`__ is a fantastic (and free) online book for
+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
diff --git a/docs/intro/index.txt b/docs/intro/index.txt
index a7872017b9..18664ef053 100644
--- a/docs/intro/index.txt
+++ b/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 3`_, also available in a
- `dead-tree version`_). If that's not quite your style, there are quite
- a few other `books about Python`_.
+ Python quickly, we recommend `Dive Into Python`_. If that's not quite your
+ style, there are many 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/
- .. _Python 3: http://diveintopython3.net/
- .. _dead-tree version: http://www.amazon.com/exec/obidos/ASIN/1590593561/ref=nosim/jacobian20
+ .. _Dive Into Python: http://diveintopython3.net/
.. _books about Python: https://wiki.python.org/moin/PythonBooks
diff --git a/docs/intro/install.txt b/docs/intro/install.txt
index 3ef59dcafb..1d58b5dc3f 100644
--- a/docs/intro/install.txt
+++ b/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
-probably already have it installed.
+Get the latest version of Python at http://www.python.org/download/ or with
+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)
- [GCC 4.7.2] on linux2
+ Python 3.3.3 (default, Nov 26 2013, 13:33:18)
+ [GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt
index 2a1b979a20..6ec3baf0ec 100644
--- a/docs/intro/overview.txt
+++ b/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 __unicode__(self):
+ def __str__(self): # __unicode__ on Python 2
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 __unicode__(self):
+ def __str__(self): # __unicode__ on Python 2
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
-by creating a new base template.
+technique to create strikingly different mobile versions of sites -- simply by
+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
diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt
index 4c6e2173db..7f1d984d1f 100644
--- a/docs/intro/reusable-apps.txt
+++ b/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
- 'Programming Language :: Python :: 2',
- 'Programming Language :: Python :: 2.7',
+ # Replace these appropriately if you are stuck on Python 2.
+ 'Programming Language :: Python :: 3',
+ 'Programming Language :: Python :: 3.2',
+ 'Programming Language :: Python :: 3.3',
'Topic :: Internet :: WWW/HTTP',
'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
],
diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt
index e8b6fc10e0..4382f21a0f 100644
--- a/docs/intro/tutorial01.txt
+++ b/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
-version doesn't match, you can refer to the tutorial for your version of
-Django by using the version switcher at the bottom right corner of this page,
-or update Django to the newest version. If you are using Python 3.x, be aware
-that your code may need to differ from what is in the tutorial and you should
-continue using the tutorial only if you know what you are doing with Python
-3.x.
+This tutorial is written for Django |version| and Python 3.2 or later. If the
+Django version doesn't match, you can refer to the tutorial for your version
+of Django by using the version switcher at the bottom right corner of this
+page, or update Django to the newest version. If you are still using Python
+2.7, you will need to adjust the code samples slightly, as described in
+comments.
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
- files don't trigger a restart, so you'll have to restart the server in
- these cases.
+ effect. However, some actions like adding files don't trigger a restart,
+ so you'll have to restart the server in 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
- <DATABASE-ENGINE>`.
+ ``'django.db.backends.oracle'``. Other backends are :ref:`also available
+ <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
-``Choice``. On Python 3, simply replace ``__unicode__`` by ``__str__`` in the
-following example:
+:meth:`~django.db.models.Model.__str__` method to both ``Question`` and
+``Choice``:
.. 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
-:meth:`~django.db.models.Model.__str__` on Python 3) 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.
+It's important to add :meth:`~django.db.models.Model.__str__` 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.
-.. admonition:: ``__unicode__`` or ``__str__``?
+.. admonition:: ``__str__`` or ``__unicode__``?
- On Python 3, things are simpler, just use
- :meth:`~django.db.models.Model.__str__` and forget about
- :meth:`~django.db.models.Model.__unicode__`.
+ On Python 3, it's easy, just use
+ :meth:`~django.db.models.Model.__str__`.
- If you're familiar with Python 2, you might be in the habit of adding
- :meth:`~django.db.models.Model.__str__` methods to your classes, not
- :meth:`~django.db.models.Model.__unicode__` methods. We use
- :meth:`~django.db.models.Model.__unicode__` here because Django models deal
- with Unicode by default. All data stored in your database is converted to
- Unicode when it's returned.
+ On Python 2, you should define :meth:`~django.db.models.Model.__unicode__`
+ methods returning ``unicode`` values instead. Django models have a default
+ :meth:`~django.db.models.Model.__str__` method 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 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
- 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.
+ If all of this is gibberish to you, just use Python 3.
Note these are normal Python methods. Let's add a custom method, just for
demonstration:
diff --git a/docs/topics/install.txt b/docs/topics/install.txt
index d14f40a7bb..c410f86831 100644
--- a/docs/topics/install.txt
+++ b/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
-probably already have it installed.
+Get the latest version of Python at http://www.python.org/download/ or with
+your operating system's package manager.
.. admonition:: Django on Jython