innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Assumed Python 3 throughout docs/intro. 

Various small fixes while I was proof-reading.
This commit is contained in:
Aymeric Augustin 2013-12-30 18:15:49 +01:00
parent 7d7b27d2b1
commit 99649ddcb2
7 changed files with 58 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/intro/contributing.txt
View File

@ -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

10
docs/intro/index.txt
View File

@ -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

8
docs/intro/install.txt
View File

@ -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.
>>>

23
docs/intro/overview.txt
View File

@ -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

7
docs/intro/reusable-apps.txt
View File

@ -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',
],

74
docs/intro/tutorial01.txt
View File

@ -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:

4
docs/topics/install.txt
View File

@ -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