From de99f558d806a2a1b30072ec95bc44d412d80dab Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Fri, 25 Sep 2015 13:28:12 -0400 Subject: [PATCH] Fixed #25462 -- Removed Model.__unicode__() in favor of @python_2_unicode_compatible. --- docs/intro/tutorial02.txt | 24 +++--------- docs/ref/models/instances.txt | 69 ++++------------------------------- docs/topics/db/models.txt | 6 +-- 3 files changed, 16 insertions(+), 83 deletions(-) diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index de1f43708f..a92b757279 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -445,15 +445,18 @@ of this object. Let's fix that by editing the ``Question`` model (in the :filename: polls/models.py from django.db import models + from django.utils.encoding import python_2_unicode_compatible + @python_2_unicode_compatible # only if you need to support Python 2 class Question(models.Model): # ... - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.question_text + @python_2_unicode_compatible # only if you need to support Python 2 class Choice(models.Model): # ... - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.choice_text It's important to add :meth:`~django.db.models.Model.__str__` methods to your @@ -461,23 +464,6 @@ models, not only for your own convenience when dealing with the interactive prompt, but also because objects' representations are used throughout Django's automatically-generated admin. -.. admonition:: ``__str__`` or ``__unicode__``? - - On Python 3, it's easy, just use - :meth:`~django.db.models.Model.__str__`. - - 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: ``object`` has a ``__unicode__`` - method that calls ``__str__`` and interprets the result as an ASCII - bytestring. This difference can create confusion. - - 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/ref/models/instances.txt b/docs/ref/models/instances.txt index 86438b64bc..16786c09d0 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -588,58 +588,23 @@ Other model instance methods 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__`` ---------------- - -.. method:: Model.__unicode__() - -The ``__unicode__()`` method is called whenever you call ``unicode()`` on an -object. Django uses ``unicode(obj)`` (or the related function, :meth:`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 ``__unicode__()`` 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 __unicode__(self): - return u'%s %s' % (self.first_name, self.last_name) - -If you define a ``__unicode__()`` method on your model and not a -:meth:`~Model.__str__()` method, Django will automatically provide you with a -:meth:`~Model.__str__()` that calls ``__unicode__()`` and then converts the -result correctly to a UTF-8 encoded string object. This is recommended -development practice: define only ``__unicode__()`` and let Django take care of -the conversion to string objects when required. - ``__str__`` ----------- .. method:: Model.__str__() -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 +The ``__str__()`` method is called whenever you call ``str()`` on an object. +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 + from django.utils.encoding import python_2_unicode_compatible + @python_2_unicode_compatible # only if you need to support Python 2 class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) @@ -647,26 +612,8 @@ For example:: 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:: - - from django.db import models - from django.utils.encoding import force_bytes - - class Person(models.Model): - first_name = models.CharField(max_length=50) - last_name = models.CharField(max_length=50) - - def __str__(self): - # Note use of django.utils.encoding.force_bytes() here because - # first_name and last_name will be unicode strings. - return force_bytes('%s %s' % (self.first_name, self.last_name)) +If you'd like compatibility with Python 2, you can decorate your model class +with :func:`~django.utils.encoding.python_2_unicode_compatible` as show above. ``__eq__`` ---------- diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index ed13e46374..53d2396f03 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -756,9 +756,6 @@ 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: :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 object. This is what Python and Django will use whenever a model instance needs to be coerced and displayed as a plain string. Most @@ -768,6 +765,9 @@ below -- but there are a couple that you'll almost always want to define: You'll always want to define this method; the default isn't very helpful at all. +``__unicode__()`` (Python 2) + Python 2 equivalent of ``__str__()``. + :meth:`~Model.get_absolute_url` This tells Django how to calculate the URL for an object. Django uses this in its admin interface, and any time it needs to figure out a URL