[py3] Documented forwards-compatible aliases

that will be available as of version 1.4.2.
This commit is contained in:
Aymeric Augustin 2012-09-07 11:57:46 -04:00
parent cceff73acd
commit e1a37d5537
1 changed files with 13 additions and 5 deletions

View File

@ -25,10 +25,11 @@ free to chose another strategy for your own code, especially if you don't need
to stay compatible with Python 2. But authors of pluggable applications are to stay compatible with Python 2. But authors of pluggable applications are
encouraged to use the same porting strategy as Django itself. encouraged to use the same porting strategy as Django itself.
Writing compatible code is much easier if you target Python ≥ 2.6. You will Writing compatible code is much easier if you target Python ≥ 2.6. Django 1.5
most likely take advantage of the compatibility functions introduced in Django introduces compatibility tools such as :mod:`django.utils.six`. For
1.5, like :mod:`django.utils.six`, so your application will also require convenience, forwards-compatible aliases were introduced in Django 1.4.2. If
Django ≥ 1.5. your application takes advantage of these tools, it will require Django ≥
1.4.2.
Obviously, writing compatible source code adds some overhead, and that can Obviously, writing compatible source code adds some overhead, and that can
cause frustration. Django's developers have found that attempting to write cause frustration. Django's developers have found that attempting to write
@ -102,6 +103,8 @@ Old name New name
For backwards compatibility, the old names still work on Python 2. Under For backwards compatibility, the old names still work on Python 2. Under
Python 3, ``smart_str`` is an alias for ``smart_text``. Python 3, ``smart_str`` is an alias for ``smart_text``.
For forwards compatibility, the new names work as of Django 1.4.2.
.. note:: .. note::
:mod:`django.utils.encoding` was deeply refactored in Django 1.5 to :mod:`django.utils.encoding` was deeply refactored in Django 1.5 to
@ -126,6 +129,8 @@ For backwards compatibility, the old names still work on Python 2. Under
Python 3, ``EscapeString`` and ``SafeString`` are aliases for ``EscapeText`` Python 3, ``EscapeString`` and ``SafeString`` are aliases for ``EscapeText``
and ``SafeText`` respectively. and ``SafeText`` respectively.
For forwards compatibility, the new names work as of Django 1.4.2.
:meth:`__str__` and :meth:`__unicode__` methods :meth:`__str__` and :meth:`__unicode__` methods
----------------------------------------------- -----------------------------------------------
@ -166,6 +171,8 @@ On Python 3, the decorator is a no-op. On Python 2, it defines appropriate
This technique is the best match for Django's porting philosophy. This technique is the best match for Django's porting philosophy.
For forwards compatibility, this decorator is available as of Django 1.4.2.
Finally, note that :meth:`__repr__` must return a :class:`str` on all versions Finally, note that :meth:`__repr__` must return a :class:`str` on all versions
of Python. of Python.
@ -317,7 +324,8 @@ Writing compatible code with six
six_ is the canonical compatibility library for supporting Python 2 and 3 in six_ is the canonical compatibility library for supporting Python 2 and 3 in
a single codebase. Read its documentation! a single codebase. Read its documentation!
:mod:`six` is bundled with Django: you can import it as :mod:`django.utils.six`. :mod`six` is bundled with Django as of version 1.4.2. You can import it as
:mod`django.utils.six`.
Here are the most common changes required to write compatible code. Here are the most common changes required to write compatible code.