Fixed #20224 -- Update docs examples which mention __unicode__

Thanks Marc Tamlyn and Tim Graham for the review.
This commit is contained in:
Claude Paroz 2013-07-04 15:19:33 +02:00
parent 577b0f9189
commit 7442eb1a24
24 changed files with 65 additions and 24 deletions

View File

@ -53,7 +53,7 @@ class Command(LabelCommand):
make_option('--multi-geom', action='store_true', dest='multi_geom', default=False, make_option('--multi-geom', action='store_true', dest='multi_geom', default=False,
help='Treat the geometry in the data source as a geometry collection.'), help='Treat the geometry in the data source as a geometry collection.'),
make_option('--name-field', dest='name_field', make_option('--name-field', dest='name_field',
help='Specifies a field name to return for the `__unicode__` function.'), help='Specifies a field name to return for the `__unicode__`/`__str__` function.'),
make_option('--no-imports', action='store_false', dest='imports', default=True, make_option('--no-imports', action='store_false', dest='imports', default=True,
help='Do not include `from django.contrib.gis.db import models` ' help='Do not include `from django.contrib.gis.db import models` '
'statement.'), 'statement.'),

View File

@ -89,7 +89,7 @@ def ogrinspect(*args, **kwargs):
`multi_geom` => Boolean (default: False) - specify as multigeometry. `multi_geom` => Boolean (default: False) - specify as multigeometry.
`name_field` => String - specifies a field name to return for the `name_field` => String - specifies a field name to return for the
`__unicode__` function (which will be generated if specified). `__unicode__`/`__str__` function (which will be generated if specified).
`imports` => Boolean (default: True) - set to False to omit the `imports` => Boolean (default: True) - set to False to omit the
`from django.contrib.gis.db import models` code from the `from django.contrib.gis.db import models` code from the
@ -221,4 +221,5 @@ def _ogrinspect(data_source, model_name, geom_name='geom', layer_key=0, srid=Non
if name_field: if name_field:
yield '' yield ''
yield ' def __str__(self): return self.%s' % name_field yield ' def __%s__(self): return self.%s' % (
'str' if six.PY3 else 'unicode', name_field)

View File

@ -710,9 +710,9 @@ smoothly:
behavior of the field code is to call behavior of the field code is to call
:func:`~django.utils.encoding.force_text` on the value. (In our :func:`~django.utils.encoding.force_text` on the value. (In our
examples in this document, ``value`` would be a ``Hand`` instance, not a examples in this document, ``value`` would be a ``Hand`` instance, not a
``HandField``). So if your ``__unicode__()`` method automatically ``HandField``). So if your ``__unicode__()`` method (``__str__()`` on
converts to the string form of your Python object, you can save yourself Python 3) automatically converts to the string form of your Python object,
a lot of work. you can save yourself a lot of work.
Writing a ``FileField`` subclass Writing a ``FileField`` subclass

View File

@ -124,13 +124,16 @@ Model style
first_name = models.CharField(max_length=20) first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40) last_name = models.CharField(max_length=40)
* If you define a ``__str__`` method (previously ``__unicode__`` before Python 3
was supported), decorate the model class with
:func:`~django.utils.encoding.python_2_unicode_compatible`.
* The order of model inner classes and standard methods should be as * The order of model inner classes and standard methods should be as
follows (noting that these are not all required): follows (noting that these are not all required):
* All database fields * All database fields
* Custom manager attributes * Custom manager attributes
* ``class Meta`` * ``class Meta``
* ``def __unicode__()``
* ``def __str__()`` * ``def __str__()``
* ``def save()`` * ``def save()``
* ``def get_absolute_url()`` * ``def get_absolute_url()``

View File

@ -31,6 +31,7 @@ the file ``mysite/news/models.py``::
class Reporter(models.Model): class Reporter(models.Model):
full_name = models.CharField(max_length=70) full_name = models.CharField(max_length=70)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.full_name return self.full_name
@ -40,6 +41,7 @@ the file ``mysite/news/models.py``::
content = models.TextField() content = models.TextField()
reporter = models.ForeignKey(Reporter) reporter = models.ForeignKey(Reporter)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.headline return self.headline

View File

@ -57,6 +57,7 @@ simple news application with an ``Article`` model::
body = models.TextField() body = models.TextField()
status = models.CharField(max_length=1, choices=STATUS_CHOICES) status = models.CharField(max_length=1, choices=STATUS_CHOICES)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.title return self.title

View File

@ -438,7 +438,8 @@ subclass::
list_display = ('first_name', 'last_name') list_display = ('first_name', 'last_name')
If you don't set ``list_display``, the admin site will display a single If you don't set ``list_display``, the admin site will display a single
column that displays the ``__unicode__()`` representation of each object. column that displays the ``__unicode__()`` (``__str__()`` on Python 3)
representation of each object.
You have four possible values that can be used in ``list_display``: You have four possible values that can be used in ``list_display``:
@ -488,7 +489,7 @@ subclass::
A few special cases to note about ``list_display``: A few special cases to note about ``list_display``:
* If the field is a ``ForeignKey``, Django will display the * If the field is a ``ForeignKey``, Django will display the
``__unicode__()`` of the related object. ``__unicode__()`` (``__str__()`` on Python 3) of the related object.
* ``ManyToManyField`` fields aren't supported, because that would * ``ManyToManyField`` fields aren't supported, because that would
entail executing a separate SQL statement for each row in the table. entail executing a separate SQL statement for each row in the table.

View File

@ -270,6 +270,7 @@ A simple example is a tagging system, which might look like this::
object_id = models.PositiveIntegerField() object_id = models.PositiveIntegerField()
content_object = generic.GenericForeignKey('content_type', 'object_id') content_object = generic.GenericForeignKey('content_type', 'object_id')
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.tag return self.tag

View File

@ -65,8 +65,8 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
.. django-admin-option:: --name-field <name_field> .. django-admin-option:: --name-field <name_field>
Generates a ``__unicode__`` routine on the model that will return the Generates a ``__unicode__`` routine (``__str__`` on Python 3) on the model
the given field name. that will return the the given field name.
.. django-admin-option:: --no-imports .. django-admin-option:: --no-imports

View File

@ -60,6 +60,8 @@ Example
name = models.CharField(max_length=25) # corresponds to the 'str' field name = models.CharField(max_length=25) # corresponds to the 'str' field
poly = models.PolygonField(srid=4269) # we want our model in a different SRID poly = models.PolygonField(srid=4269) # we want our model in a different SRID
objects = models.GeoManager() objects = models.GeoManager()
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return 'Name: %s' % self.name return 'Name: %s' % self.name

View File

@ -244,6 +244,7 @@ model to represent this data::
objects = models.GeoManager() objects = models.GeoManager()
# Returns the string representation of the model. # Returns the string representation of the model.
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name

View File

@ -566,7 +566,8 @@ Customizing the error list format
By default, forms use ``django.forms.util.ErrorList`` to format validation By default, forms use ``django.forms.util.ErrorList`` to format validation
errors. If you'd like to use an alternate class for displaying errors, you can errors. If you'd like to use an alternate class for displaying errors, you can
pass that in at construction time:: pass that in at construction time (replace ``__unicode__`` by ``__str__`` on
Python 3)::
>>> from django.forms.util import ErrorList >>> from django.forms.util import ErrorList
>>> class DivErrorList(ErrorList): >>> class DivErrorList(ErrorList):

View File

@ -1000,12 +1000,12 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
initial value, no empty choice is created (regardless of the value initial value, no empty choice is created (regardless of the value
of ``empty_label``). of ``empty_label``).
The ``__unicode__`` method of the model will be called to generate The ``__unicode__`` (``__str__`` on Python 3) method of the model will be
string representations of the objects for use in the field's choices; called to generate string representations of the objects for use in the
to provide customized representations, subclass ``ModelChoiceField`` field's choices; to provide customized representations, subclass
and override ``label_from_instance``. This method will receive a model ``ModelChoiceField`` and override ``label_from_instance``. This method will
object, and should return a string suitable for representing it. For receive a model object, and should return a string suitable for representing
example:: it. For example::
from django.forms import ModelChoiceField from django.forms import ModelChoiceField

View File

@ -430,6 +430,12 @@ Other model instance methods
A few object methods have special purposes. A few object methods have special purposes.
.. note::
On Python 3, as all strings are natively considered Unicode, only use the
``__str__()`` method (the ``__unicode__()`` method is obsolete).
If you'd like compatibility with Python 2, you can decorate your model class
with :func:`~django.utils.encoding.python_2_unicode_compatible`.
``__unicode__`` ``__unicode__``
--------------- ---------------

View File

@ -814,6 +814,7 @@ For example, suppose you have these models::
name = models.CharField(max_length=50) name = models.CharField(max_length=50)
toppings = models.ManyToManyField(Topping) toppings = models.ManyToManyField(Topping)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return u"%s (%s)" % (self.name, u", ".join([topping.name return u"%s (%s)" % (self.name, u", ".join([topping.name
for topping in self.toppings.all()])) for topping in self.toppings.all()]))

View File

@ -446,12 +446,14 @@ Atom1Feed
def fancy_utility_function(s, ...): def fancy_utility_function(s, ...):
# Do some conversion on string 's' # Do some conversion on string 's'
... ...
# Replace unicode by str on Python 3
fancy_utility_function = allow_lazy(fancy_utility_function, unicode) fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
The ``allow_lazy()`` decorator takes, in addition to the function to decorate, The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
a number of extra arguments (``*args``) specifying the type(s) that the a number of extra arguments (``*args``) specifying the type(s) that the
original function can return. Usually, it's enough to include ``unicode`` here original function can return. Usually, it's enough to include ``unicode``
and ensure that your function returns only Unicode strings. (or ``str`` on Python 3) here and ensure that your function returns only
Unicode strings.
Using this decorator means you can write your function and assume that the Using this decorator means you can write your function and assume that the
input is a proper string, then add support for lazy translation objects at the input is a proper string, then add support for lazy translation objects at the

View File

@ -968,6 +968,7 @@ authentication app::
# The user is identified by their email address # The user is identified by their email address
return self.email return self.email
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.email return self.email

View File

@ -89,6 +89,7 @@ We'll be using these models::
class Meta: class Meta:
ordering = ["-name"] ordering = ["-name"]
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name
@ -98,6 +99,7 @@ We'll be using these models::
email = models.EmailField() email = models.EmailField()
headshot = models.ImageField(upload_to='author_headshots') headshot = models.ImageField(upload_to='author_headshots')
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name

View File

@ -16,6 +16,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects:
class Publication(models.Model): class Publication(models.Model):
title = models.CharField(max_length=30) title = models.CharField(max_length=30)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.title return self.title
@ -26,6 +27,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects:
headline = models.CharField(max_length=100) headline = models.CharField(max_length=100)
publications = models.ManyToManyField(Publication) publications = models.ManyToManyField(Publication)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.headline return self.headline

View File

@ -15,6 +15,7 @@ To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`.
last_name = models.CharField(max_length=30) last_name = models.CharField(max_length=30)
email = models.EmailField() email = models.EmailField()
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return u"%s %s" % (self.first_name, self.last_name) return u"%s %s" % (self.first_name, self.last_name)
@ -23,6 +24,7 @@ To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`.
pub_date = models.DateField() pub_date = models.DateField()
reporter = models.ForeignKey(Reporter) reporter = models.ForeignKey(Reporter)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.headline return self.headline
@ -56,9 +58,9 @@ Article objects have access to their related Reporter objects::
>>> r = a.reporter >>> r = a.reporter
These are strings instead of unicode strings because that's what was used in On Python 2, these are strings of type ``str`` instead of unicode strings
the creation of this reporter (and we haven't refreshed the data from the because that's what was used in the creation of this reporter (and we haven't
database, which always returns unicode strings):: refreshed the data from the database, which always returns unicode strings)::
>>> r.first_name, r.last_name >>> r.first_name, r.last_name
('John', 'Smith') ('John', 'Smith')

View File

@ -16,6 +16,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
name = models.CharField(max_length=50) name = models.CharField(max_length=50)
address = models.CharField(max_length=80) address = models.CharField(max_length=80)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return u"%s the place" % self.name return u"%s the place" % self.name
@ -24,6 +25,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
serves_hot_dogs = models.BooleanField() serves_hot_dogs = models.BooleanField()
serves_pizza = models.BooleanField() serves_pizza = models.BooleanField()
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return u"%s the restaurant" % self.place.name return u"%s the restaurant" % self.place.name
@ -31,6 +33,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
restaurant = models.ForeignKey(Restaurant) restaurant = models.ForeignKey(Restaurant)
name = models.CharField(max_length=50) name = models.CharField(max_length=50)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return u"%s the waiter at %s" % (self.name, self.restaurant) return u"%s the waiter at %s" % (self.name, self.restaurant)

View File

@ -416,6 +416,7 @@ something like this::
class Person(models.Model): class Person(models.Model):
name = models.CharField(max_length=128) name = models.CharField(max_length=128)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name
@ -423,6 +424,7 @@ something like this::
name = models.CharField(max_length=128) name = models.CharField(max_length=128)
members = models.ManyToManyField(Person, through='Membership') members = models.ManyToManyField(Person, through='Membership')
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name
@ -709,7 +711,10 @@ of :ref:`methods automatically given to each model <model-instance-methods>`.
You can override most of these -- see `overriding predefined model methods`_, You can override most of these -- see `overriding predefined model methods`_,
below -- but there are a couple that you'll almost always want to define: below -- but there are a couple that you'll almost always want to define:
:meth:`~Model.__unicode__` :meth:`~Model.__str__` (Python 3)
Python 3 equivalent of ``__unicode__()``.
:meth:`~Model.__unicode__` (Python 2)
A Python "magic method" that returns a unicode "representation" of any A Python "magic method" that returns a unicode "representation" of any
object. This is what Python and Django will use whenever a model object. This is what Python and Django will use whenever a model
instance needs to be coerced and displayed as a plain string. Most instance needs to be coerced and displayed as a plain string. Most

View File

@ -23,6 +23,7 @@ models, which comprise a Weblog application:
name = models.CharField(max_length=100) name = models.CharField(max_length=100)
tagline = models.TextField() tagline = models.TextField()
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name
@ -30,6 +31,7 @@ models, which comprise a Weblog application:
name = models.CharField(max_length=50) name = models.CharField(max_length=50)
email = models.EmailField() email = models.EmailField()
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name
@ -44,6 +46,7 @@ models, which comprise a Weblog application:
n_pingbacks = models.IntegerField() n_pingbacks = models.IntegerField()
rating = models.IntegerField() rating = models.IntegerField()
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.headline return self.headline

View File

@ -162,6 +162,7 @@ Consider this set of models::
title = models.CharField(max_length=3, choices=TITLE_CHOICES) title = models.CharField(max_length=3, choices=TITLE_CHOICES)
birth_date = models.DateField(blank=True, null=True) birth_date = models.DateField(blank=True, null=True)
# On Python 3: def __str__(self):
def __unicode__(self): def __unicode__(self):
return self.name return self.name