From 8aa1efff6d6cb1589a1977f3e68f4c26eb6adc74 Mon Sep 17 00:00:00 2001 From: Alasdair Nicol Date: Sun, 9 Feb 2014 11:38:13 +0000 Subject: [PATCH] Fixed #21951 -- Updated docs to use __str__ for Python 3 Thanks Tim Graham for the report and recommendations --- docs/howto/custom-model-fields.txt | 6 ++--- docs/intro/tutorial01.txt | 2 +- docs/ref/contrib/admin/actions.txt | 3 +-- docs/ref/contrib/admin/index.txt | 12 ++++----- docs/ref/contrib/contenttypes.txt | 3 +-- docs/ref/contrib/gis/commands.txt | 2 +- docs/ref/contrib/gis/layermapping.txt | 3 +-- docs/ref/contrib/gis/tutorial.txt | 3 +-- docs/ref/forms/api.txt | 14 +++++----- docs/ref/forms/fields.txt | 2 +- docs/ref/models/instances.txt | 26 ++++++++++++++++--- docs/ref/models/querysets.txt | 11 ++++---- docs/topics/auth/customizing.txt | 3 +-- .../class-based-views/generic-display.txt | 6 ++--- docs/topics/db/examples/many_to_many.txt | 6 ++--- docs/topics/db/examples/many_to_one.txt | 8 +++--- docs/topics/db/examples/one_to_one.txt | 15 +++++------ docs/topics/db/models.txt | 6 ++--- docs/topics/db/queries.txt | 9 +++---- docs/topics/forms/modelforms.txt | 3 +-- 20 files changed, 71 insertions(+), 72 deletions(-) diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 2c2f6d3d4d..12cc861746 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -817,13 +817,13 @@ smoothly: a field that's similar to what you want and extend it a little bit, instead of creating an entirely new field from scratch. -2. Put a ``__str__()`` or ``__unicode__()`` method on the class you're +2. Put a ``__str__()`` (``__unicode__()`` on Python 2) method on the class you're wrapping up as a field. There are a lot of places where the default behavior of the field code is to call :func:`~django.utils.encoding.force_text` on the value. (In our examples in this document, ``value`` would be a ``Hand`` instance, not a - ``HandField``). So if your ``__unicode__()`` method (``__str__()`` on - Python 3) automatically converts to the string form of your Python object, + ``HandField``). So if your ``__str__()`` method (``__unicode__()`` on + Python 2) automatically converts to the string form of your Python object, you can save yourself a lot of work. diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 16b2596da9..bc050c535d 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -727,7 +727,7 @@ Save these changes and start a new Python interactive shell by running >>> from polls.models import Question, Choice - # Make sure our __unicode__() addition worked. + # Make sure our __str__() addition worked. >>> Question.objects.all() [] diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index b982aa64f7..a892f41106 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -57,8 +57,7 @@ simple news application with an ``Article`` model:: body = models.TextField() status = models.CharField(max_length=1, choices=STATUS_CHOICES) - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.title A common task we might perform with a model like this is to update an diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 14d2a69d7f..28de1aa612 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -512,7 +512,7 @@ subclass:: list_display = ('first_name', 'last_name') If you don't set ``list_display``, the admin site will display a single - column that displays the ``__unicode__()`` (``__str__()`` on Python 3) + column that displays the ``__str__()`` (``__unicode__()`` on Python 2) representation of each object. You have four possible values that can be used in ``list_display``: @@ -563,7 +563,7 @@ subclass:: A few special cases to note about ``list_display``: * If the field is a ``ForeignKey``, Django will display the - ``__unicode__()`` (``__str__()`` on Python 3) of the related object. + ``__str__()`` (``__unicode__()`` on Python 2) of the related object. * ``ManyToManyField`` fields aren't supported, because that would entail executing a separate SQL statement for each row in the table. @@ -626,11 +626,11 @@ subclass:: list_display = ('name', 'born_in_fifties') - * The ``__str__()`` and ``__unicode__()`` methods are just as valid in - ``list_display`` as any other model method, so it's perfectly OK to - do this:: + * The ``__str__()`` (``__unicode__()`` on Python 2) method is just + as valid in ``list_display`` as any other model method, so it's + perfectly OK to do this:: - list_display = ('__unicode__', 'some_other_field') + list_display = ('__str__', 'some_other_field') * Usually, elements of ``list_display`` that aren't actual database fields can't be used in sorting (because Django does all the sorting diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 19c2853722..d01fc6baa5 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -259,8 +259,7 @@ A simple example is a tagging system, which might look like this:: object_id = models.PositiveIntegerField() content_object = GenericForeignKey('content_type', 'object_id') - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.tag A normal :class:`~django.db.models.ForeignKey` can only "point diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index 2933f54720..a1ca5d7841 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -65,7 +65,7 @@ of using ``ogrinspect`` :ref:`in the tutorial `. .. django-admin-option:: --name-field - Generates a ``__unicode__`` routine (``__str__`` on Python 3) on the model + Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model that will return the given field name. .. django-admin-option:: --no-imports diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index 376c6115b1..e13f370652 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -61,8 +61,7 @@ Example poly = models.PolygonField(srid=4269) # we want our model in a different SRID objects = models.GeoManager() - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return 'Name: %s' % self.name 3. Use :class:`LayerMapping` to extract all the features and place them in the diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index ff27c9b6ec..24470e8227 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -244,8 +244,7 @@ model to represent this data:: objects = models.GeoManager() # Returns the string representation of the model. - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name Please note two important things: diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index fbc025f18c..7f2de3fa03 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -653,16 +653,16 @@ Customizing the error list format By default, forms use ``django.forms.utils.ErrorList`` to format validation errors. If you'd like to use an alternate class for displaying errors, you can -pass that in at construction time (replace ``__unicode__`` by ``__str__`` on -Python 3):: +pass that in at construction time (replace ``__str__`` by ``__unicode__`` on +Python 2):: >>> from django.forms.utils import ErrorList >>> class DivErrorList(ErrorList): - ... def __unicode__(self): + ... def __str__(self): # __unicode__ on Python 2 ... return self.as_divs() ... def as_divs(self): - ... if not self: return u'' - ... return u'
%s
' % ''.join([u'
%s
' % e for e in self]) + ... if not self: return '' + ... return '
%s
' % ''.join(['
%s
' % e for e in self]) >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList) >>> f.as_p()
This field is required.
@@ -687,8 +687,8 @@ lazy developers -- they're not the only way a form object can be displayed. Used to display HTML or access attributes for a single field of a :class:`Form` instance. - The ``__unicode__()`` and ``__str__()`` methods of this object displays - the HTML for this field. + The ``__str__()`` (``__unicode__`` on Python 2) method of this + object displays the HTML for this field. To retrieve a single ``BoundField``, use dictionary lookup syntax on your form using the field's name as the key:: diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 42d639e8c7..f48f9ff4ad 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -1047,7 +1047,7 @@ objects (in the case of ``ModelMultipleChoiceField``) into the initial value, no empty choice is created (regardless of the value of ``empty_label``). - The ``__unicode__`` (``__str__`` on Python 3) method of the model will be + The ``__str__`` (``__unicode__`` on Python 2) method of the model will be called to generate string representations of the objects for use in the field's choices; to provide customized representations, subclass ``ModelChoiceField`` and override ``label_from_instance``. This method will diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 2177bc6a59..2371fd3c8a 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -463,9 +463,29 @@ the conversion to string objects when required. .. method:: Model.__str__() -The ``__str__()`` method is called whenever you call ``str()`` on an object. The main use for this method directly inside Django is when the ``repr()`` output of a model is displayed anywhere (for example, in debugging output). -Thus, you should return a nice, human-readable string for the object's -``__str__()``. It isn't required to put ``__str__()`` methods everywhere if you have sensible :meth:`~Model.__unicode__()` methods. +The ``__str__()`` method is called whenever you call ``str()`` on an +object. In Python 3, Django uses ``str(obj)`` in a number of +places. Most notably, to display an object in the Django admin site +and as the value inserted into a template when it displays an +object. Thus, you should always return a nice, human-readable +representation of the model from the ``__str__()`` method. + +For example:: + + from django.db import models + + class Person(models.Model): + first_name = models.CharField(max_length=50) + last_name = models.CharField(max_length=50) + + def __str__(self): + return '%s %s' % (self.first_name, self.last_name) + +In Python 2, the main use of ``__str__`` directly inside Django is +when the ``repr()`` output of a model is displayed anywhere (for +example, in debugging output). It isn't required to put ``__str__()`` +methods everywhere if you have sensible :meth:`~Model.__unicode__()` +methods. The previous :meth:`~Model.__unicode__()` example could be similarly written using ``__str__()`` like this:: diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index c063d38aa6..94f9c6b36b 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -812,17 +812,16 @@ For example, suppose you have these models:: name = models.CharField(max_length=50) toppings = models.ManyToManyField(Topping) - # On Python 3: def __str__(self): - def __unicode__(self): - return u"%s (%s)" % (self.name, u", ".join([topping.name - for topping in self.toppings.all()])) + def __str__(self): # __unicode__ on Python 2 + return "%s (%s)" % (self.name, ", ".join([topping.name + for topping in self.toppings.all()])) and run:: >>> Pizza.objects.all() - [u"Hawaiian (ham, pineapple)", u"Seafood (prawns, smoked salmon)"... + ["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"... -The problem with this is that every time ``Pizza.__unicode__()`` asks for +The problem with this is that every time ``Pizza.__str__()`` asks for ``self.toppings.all()`` it has to query the database, so ``Pizza.objects.all()`` will run a query on the Toppings table for **every** item in the Pizza ``QuerySet``. diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index a65d498f07..b85d08ad56 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -984,8 +984,7 @@ authentication app:: # The user is identified by their email address return self.email - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.email def has_perm(self, perm, obj=None): diff --git a/docs/topics/class-based-views/generic-display.txt b/docs/topics/class-based-views/generic-display.txt index 2f8d561541..57c7a0d02f 100644 --- a/docs/topics/class-based-views/generic-display.txt +++ b/docs/topics/class-based-views/generic-display.txt @@ -89,8 +89,7 @@ We'll be using these models:: class Meta: ordering = ["-name"] - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Author(models.Model): @@ -99,8 +98,7 @@ We'll be using these models:: email = models.EmailField() headshot = models.ImageField(upload_to='author_headshots') - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Book(models.Model): diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt index d127b93b0a..cd38d57b45 100644 --- a/docs/topics/db/examples/many_to_many.txt +++ b/docs/topics/db/examples/many_to_many.txt @@ -16,8 +16,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects: class Publication(models.Model): title = models.CharField(max_length=30) - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.title class Meta: @@ -27,8 +26,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects: headline = models.CharField(max_length=100) publications = models.ManyToManyField(Publication) - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.headline class Meta: diff --git a/docs/topics/db/examples/many_to_one.txt b/docs/topics/db/examples/many_to_one.txt index 983bc2eed4..1101865755 100644 --- a/docs/topics/db/examples/many_to_one.txt +++ b/docs/topics/db/examples/many_to_one.txt @@ -15,17 +15,15 @@ To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`. last_name = models.CharField(max_length=30) email = models.EmailField() - # On Python 3: def __str__(self): - def __unicode__(self): - return u"%s %s" % (self.first_name, self.last_name) + def __str__(self): # __unicode__ on Python 2 + return "%s %s" % (self.first_name, self.last_name) class Article(models.Model): headline = models.CharField(max_length=100) pub_date = models.DateField() reporter = models.ForeignKey(Reporter) - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.headline class Meta: diff --git a/docs/topics/db/examples/one_to_one.txt b/docs/topics/db/examples/one_to_one.txt index 994794c43b..89d422aecd 100644 --- a/docs/topics/db/examples/one_to_one.txt +++ b/docs/topics/db/examples/one_to_one.txt @@ -16,26 +16,23 @@ In this example, a ``Place`` optionally can be a ``Restaurant``: name = models.CharField(max_length=50) address = models.CharField(max_length=80) - # On Python 3: def __str__(self): - def __unicode__(self): - return u"%s the place" % self.name + def __str__(self): # __unicode__ on Python 2 + return "%s the place" % self.name class Restaurant(models.Model): place = models.OneToOneField(Place, primary_key=True) serves_hot_dogs = models.BooleanField() serves_pizza = models.BooleanField() - # On Python 3: def __str__(self): - def __unicode__(self): - return u"%s the restaurant" % self.place.name + def __str__(self): # __unicode__ on Python 2 + return "%s the restaurant" % self.place.name class Waiter(models.Model): restaurant = models.ForeignKey(Restaurant) name = models.CharField(max_length=50) - # On Python 3: def __str__(self): - def __unicode__(self): - return u"%s the waiter at %s" % (self.name, self.restaurant) + def __str__(self): # __unicode__ on Python 2 + return "%s the waiter at %s" % (self.name, self.restaurant) What follows are examples of operations that can be performed using the Python API facilities. diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 51fa51194a..5039bbd2d1 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -417,16 +417,14 @@ something like this:: class Person(models.Model): name = models.CharField(max_length=128) - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Group(models.Model): name = models.CharField(max_length=128) members = models.ManyToManyField(Person, through='Membership') - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Membership(models.Model): diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 94073d1a70..2aa60be0b8 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -23,16 +23,14 @@ models, which comprise a Weblog application: name = models.CharField(max_length=100) tagline = models.TextField() - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Author(models.Model): name = models.CharField(max_length=50) email = models.EmailField() - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Entry(models.Model): @@ -46,8 +44,7 @@ models, which comprise a Weblog application: n_pingbacks = models.IntegerField() rating = models.IntegerField() - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.headline Creating objects diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 1cac2d6e7e..6222f342b4 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -162,8 +162,7 @@ Consider this set of models:: title = models.CharField(max_length=3, choices=TITLE_CHOICES) birth_date = models.DateField(blank=True, null=True) - # On Python 3: def __str__(self): - def __unicode__(self): + def __str__(self): # __unicode__ on Python 2 return self.name class Book(models.Model):