Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Fixed #20224 -- Update docs examples which mention __unicode__ #1330

Closed
wants to merge 1 commit into from

3 participants

@claudep
Collaborator

No description provided.

@mjtamlyn mjtamlyn commented on the diff
.../internals/contributing/writing-code/coding-style.txt
@@ -124,13 +124,16 @@ Model style
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
+* If you define a ``__str__`` method (previously ``__unicode__`` before Python 3
@mjtamlyn Collaborator
mjtamlyn added a note

This comment and the one above are worded differently. It would be nice to have consistency.

@claudep Collaborator
claudep added a note

Marc, I'm sorry but I'm not getting your idea here.

@mjtamlyn Collaborator
mjtamlyn added a note

Almost every place in the documentation we say "__unicode__ (or __str__ on Py3)". In this case we mention it the other way around. It's a minor point, and I guess actually as this is in the contributing docs it's a bit different. I hadn't noticed this was in contributing docs earlier which may be a bit different to user facing docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@mjtamlyn
Collaborator

So, when are we dropping 2.7? :wink:

@timgraham timgraham commented on the diff
docs/howto/custom-model-fields.txt
@@ -696,9 +696,9 @@ smoothly:
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 automatically
- converts to the string form of your Python object, you can save yourself
- a lot of work.
+ ``HandField``). So if your ``__unicode__()`` method (``__str__`` on Python 3)
@timgraham Owner

add () on str for consistency with "unicode()"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham timgraham commented on the diff
docs/ref/models/instances.txt
@@ -430,6 +430,12 @@ 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, which entirely obsoletes the ``__unicode__()`` method.
@timgraham Owner

I'd replace

", which entirely obsoletes the ``__unicode__()`` method"

with

"(the __unicode__()`` method is obsolete)"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham timgraham commented on the diff
docs/topics/db/examples/many_to_one.txt
@@ -56,9 +58,9 @@ Article objects have access to their related Reporter objects::
>>> r = a.reporter
-These are strings instead of unicode strings because that's what was used in
-the creation of this reporter (and we haven't refreshed the data from the
-database, which always returns unicode strings)::
+On Python 2, these are strings instead of unicode strings because that's what
@timgraham Owner

maybe add: strings of type str

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@claudep claudep closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
View
2  django/contrib/gis/management/commands/ogrinspect.py
@@ -53,7 +53,7 @@ class Command(LabelCommand):
make_option('--multi-geom', action='store_true', dest='multi_geom', default=False,
help='Treat the geometry in the data source as a geometry collection.'),
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,
help='Do not include `from django.contrib.gis.db import models` '
'statement.'),
View
5 django/contrib/gis/utils/ogrinspect.py
@@ -89,7 +89,7 @@ def ogrinspect(*args, **kwargs):
`multi_geom` => Boolean (default: False) - specify as multigeometry.
`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
`from django.contrib.gis.db import models` code from the
@@ -221,4 +221,5 @@ def get_kwargs_str(field_name):
if name_field:
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
6 docs/howto/custom-model-fields.txt
@@ -696,9 +696,9 @@ smoothly:
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 automatically
- converts to the string form of your Python object, you can save yourself
- a lot of work.
+ ``HandField``). So if your ``__unicode__()`` method (``__str__`` on Python 3)
@timgraham Owner

add () on str for consistency with "unicode()"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ automatically converts to the string form of your Python object, you can save
+ yourself a lot of work.
Writing a ``FileField`` subclass
View
5 docs/internals/contributing/writing-code/coding-style.txt
@@ -124,13 +124,16 @@ Model style
first_name = models.CharField(max_length=20)
last_name = models.CharField(max_length=40)
+* If you define a ``__str__`` method (previously ``__unicode__`` before Python 3
@mjtamlyn Collaborator
mjtamlyn added a note

This comment and the one above are worded differently. It would be nice to have consistency.

@claudep Collaborator
claudep added a note

Marc, I'm sorry but I'm not getting your idea here.

@mjtamlyn Collaborator
mjtamlyn added a note

Almost every place in the documentation we say "__unicode__ (or __str__ on Py3)". In this case we mention it the other way around. It's a minor point, and I guess actually as this is in the contributing docs it's a bit different. I hadn't noticed this was in contributing docs earlier which may be a bit different to user facing docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ 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
follows (noting that these are not all required):
* All database fields
* Custom manager attributes
* ``class Meta``
- * ``def __unicode__()``
* ``def __str__()``
* ``def save()``
* ``def get_absolute_url()``
View
2  docs/intro/overview.txt
@@ -31,6 +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):
return self.full_name
@@ -40,6 +41,7 @@ the file ``mysite/news/models.py``::
content = models.TextField()
reporter = models.ForeignKey(Reporter)
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.headline
View
1  docs/ref/contrib/admin/actions.txt
@@ -57,6 +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):
return self.title
View
5 docs/ref/contrib/admin/index.txt
@@ -438,7 +438,8 @@ 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__()`` 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``:
@@ -488,7 +489,7 @@ subclass::
A few special cases to note about ``list_display``:
* 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
entail executing a separate SQL statement for each row in the table.
View
1  docs/ref/contrib/contenttypes.txt
@@ -270,6 +270,7 @@ A simple example is a tagging system, which might look like this::
object_id = models.PositiveIntegerField()
content_object = generic.GenericForeignKey('content_type', 'object_id')
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.tag
View
4 docs/ref/contrib/gis/commands.txt
@@ -65,8 +65,8 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
.. django-admin-option:: --name-field <name_field>
- Generates a ``__unicode__`` routine on the model that will return the
- the given field name.
+ Generates a ``__unicode__`` routine (``__str__`` on Python 3) on the model
+ that will return the the given field name.
.. django-admin-option:: --no-imports
View
2  docs/ref/contrib/gis/layermapping.txt
@@ -60,6 +60,8 @@ Example
name = models.CharField(max_length=25) # corresponds to the 'str' field
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):
return 'Name: %s' % self.name
View
1  docs/ref/contrib/gis/tutorial.txt
@@ -244,6 +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):
return self.name
View
3  docs/ref/forms/api.txt
@@ -566,7 +566,8 @@ Customizing the error list format
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
-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
>>> class DivErrorList(ErrorList):
View
12 docs/ref/forms/fields.txt
@@ -1000,12 +1000,12 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
initial value, no empty choice is created (regardless of the value
of ``empty_label``).
- The ``__unicode__`` 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 receive a model
- object, and should return a string suitable for representing it. For
- example::
+ The ``__unicode__`` (``__str__`` on Python 3) 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
+ receive a model object, and should return a string suitable for representing
+ it. For example::
from django.forms import ModelChoiceField
View
6 docs/ref/models/instances.txt
@@ -430,6 +430,12 @@ 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, which entirely obsoletes the ``__unicode__()`` method.
@timgraham Owner

I'd replace

", which entirely obsoletes the ``__unicode__()`` method"

with

"(the __unicode__()`` method is obsolete)"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+ If you'd like compatibility with Python 2, you can decorate your model class
+ with :func:`~django.utils.encoding.python_2_unicode_compatible`.
+
``__unicode__``
---------------
View
1  docs/ref/models/querysets.txt
@@ -817,6 +817,7 @@ 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()]))
View
6 docs/ref/utils.txt
@@ -446,12 +446,14 @@ Atom1Feed
def fancy_utility_function(s, ...):
# Do some conversion on string 's'
...
+ # Replace unicode by str on Python 3
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
The ``allow_lazy()`` decorator takes, in addition to the function to decorate,
a number of extra arguments (``*args``) specifying the type(s) that the
- original function can return. Usually, it's enough to include ``unicode`` here
- and ensure that your function returns only Unicode strings.
+ original function can return. Usually, it's enough to include ``unicode``
+ (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
input is a proper string, then add support for lazy translation objects at the
View
1  docs/topics/auth/customizing.txt
@@ -967,6 +967,7 @@ authentication app::
# The user is identified by their email address
return self.email
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.email
View
2  docs/topics/class-based-views/generic-display.txt
@@ -89,6 +89,7 @@ We'll be using these models::
class Meta:
ordering = ["-name"]
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.name
@@ -98,6 +99,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):
return self.name
View
2  docs/topics/db/examples/many_to_many.txt
@@ -16,6 +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):
return self.title
@@ -26,6 +27,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):
return self.headline
View
8 docs/topics/db/examples/many_to_one.txt
@@ -15,6 +15,7 @@ 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)
@@ -23,6 +24,7 @@ To define a many-to-one relationship, use :class:`~django.db.models.ForeignKey`.
pub_date = models.DateField()
reporter = models.ForeignKey(Reporter)
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.headline
@@ -56,9 +58,9 @@ Article objects have access to their related Reporter objects::
>>> r = a.reporter
-These are strings instead of unicode strings because that's what was used in
-the creation of this reporter (and we haven't refreshed the data from the
-database, which always returns unicode strings)::
+On Python 2, these are strings instead of unicode strings because that's what
@timgraham Owner

maybe add: strings of type str

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+was used in the creation of this reporter (and we haven't refreshed the data
+from the database, which always returns unicode strings)::
>>> r.first_name, r.last_name
('John', 'Smith')
View
3  docs/topics/db/examples/one_to_one.txt
@@ -16,6 +16,7 @@ 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
@@ -24,6 +25,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
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
@@ -31,6 +33,7 @@ In this example, a ``Place`` optionally can be a ``Restaurant``:
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)
View
7 docs/topics/db/models.txt
@@ -416,6 +416,7 @@ something like this::
class Person(models.Model):
name = models.CharField(max_length=128)
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.name
@@ -423,6 +424,7 @@ something like this::
name = models.CharField(max_length=128)
members = models.ManyToManyField(Person, through='Membership')
+ # On Python 3: def __str__(self):
def __unicode__(self):
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`_,
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
object. This is what Python and Django will use whenever a model
instance needs to be coerced and displayed as a plain string. Most
View
3  docs/topics/db/queries.txt
@@ -23,6 +23,7 @@ models, which comprise a Weblog application:
name = models.CharField(max_length=100)
tagline = models.TextField()
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.name
@@ -30,6 +31,7 @@ models, which comprise a Weblog application:
name = models.CharField(max_length=50)
email = models.EmailField()
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.name
@@ -44,6 +46,7 @@ models, which comprise a Weblog application:
n_pingbacks = models.IntegerField()
rating = models.IntegerField()
+ # On Python 3: def __str__(self):
def __unicode__(self):
return self.headline
View
1  docs/topics/forms/modelforms.txt
@@ -162,6 +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):
return self.name
Something went wrong with that request. Please try again.