Updating documentation examples for Python 3

[Daniele Procida]

We received a pull request https://github.com/divio/django-cms/pull/5390, for a documentation example.

The code sample uses a Python-2-style __unicode__() method; in Python 3 it would be __str__().

It’s quite right that this needs to be updated, but we’d like to do it in a more systematic way.

The way we change examples itself needs to be consistent.


Firstly, all new and existing documentation code examples should follow the best-practice way to write Django code, which is:

* make it compatible with Python 3 by default
* use the provided shims and utilities so that the same code will *also* work with Python 2
* in the rare cases where different code is required to support both, both should be provided

This is all described, with examples, in https://docs.djangoproject.com/en/1.9/topics/python3.


Secondly, it’s not enough just to change existing examples on a case-by-case basis as people happen to find them - we’re going to have to comb through the documentation for examples, update, and test them, and then land them as far as possible en masse.

Comments? Brave volunteers?

Daniele

[Tim Graham]

It might be more effort than it's worth to test every example. Even in Django's docs, there are only a handful of places that use six:

howto/outputting-csv.txt:    from django.utils.six.moves import range
ref/urlresolvers.txt:    from django.utils.six.moves.urllib.parse import urlparse
ref/utils.txt:        from django.utils import six
topics/i18n/translation.txt:    from django.utils import six  # Python 3 compatibility
topics/testing/tools.txt:    from django.utils.six import StringIO