From 99649ddcb21b5c07258569d4585ffe3cf9eb4f38 Mon Sep 17 00:00:00 2001 From: Aymeric Augustin 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`. 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 ` 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') [] # 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 `, 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 `. You can write :doc:`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 ` 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 - `. + ``'django.db.backends.oracle'``. Other backends are :ref:`also available + `. * :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 `:: Wait a minute. ```` 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