Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[py3] Documented coding guidelines for Python 3.

  • Loading branch information...
commit 00ace01411b4cb558e71bfaf34cf42870e73092b 1 parent a84d79f
Aymeric Augustin authored
1  docs/conf.py
@@ -94,6 +94,7 @@
94 94
 intersphinx_mapping = {
95 95
     'python': ('http://docs.python.org/2.7', None),
96 96
     'sphinx': ('http://sphinx.pocoo.org/', None),
  97
+    'six': ('http://packages.python.org/six/', None),
97 98
 }
98 99
 
99 100
 # Python's docs don't change every week.
123  docs/topics/python3.txt
@@ -2,42 +2,34 @@
2 2
 Python 3 compatibility
3 3
 ======================
4 4
 
5  
-Django 1.5 is the first version of Django to support Python 3.
6  
-
7  
-The same code runs both on Python 2 (≥2.6.5) and Python 3 (≥3.2). To
8  
-achieve this:
9  
-
10  
-- wherever possible, Django uses the six_ compatibility layer,
11  
-- all modules declare ``from __future__ import unicode_literals``.
  5
+Django 1.5 is the first version of Django to support Python 3. The same code
  6
+runs both on Python 2 (≥ 2.6.5) and Python 3 (≥ 3.2), thanks to the six_
  7
+compatibility layer and ``unicode_literals``.
12 8
 
13 9
 .. _six: http://packages.python.org/six/
14 10
 
15 11
 This document is not meant as a Python 2 to Python 3 migration guide. There
16  
-are many existing resources, including `Python's official porting guide`_. But
17  
-it describes guidelines that apply to Django's code and are recommended for
18  
-pluggable apps that run with both Python 2 and 3.
  12
+are many existing resources, including `Python's official porting guide`_.
  13
+Rather, it describes guidelines that apply to Django's code and are
  14
+recommended for pluggable apps that run with both Python 2 and 3.
19 15
 
20 16
 .. _Python's official porting guide: http://docs.python.org/py3k/howto/pyporting.html
21 17
 
22  
-.. module: django.utils.six
23  
-
24  
-django.utils.six
25  
-================
26  
-
27  
-Read the documentation of six_. It's the canonical compatibility library for
28  
-supporting Python 2 and 3 in a single codebase.
  18
+Syntax requirements
  19
+===================
29 20
 
30  
-``six`` is bundled with Django: you can import it as :mod:`django.utils.six`.
  21
+Unicode
  22
+-------
31 23
 
32  
-.. _string-handling:
  24
+In Python 3, all strings are considered Unicode by default. The ``unicode``
  25
+type from Python 2 is called ``str`` in Python 3, and ``str`` becomes
  26
+``bytes``.
33 27
 
34  
-String handling
35  
-===============
  28
+You mustn't use the ``u`` prefix before a unicode string literal because it's
  29
+a syntax error in Python 3.2. You must prefix byte strings with ``b``.
36 30
 
37  
-In Python 3, all strings are considered Unicode strings by default. Byte
38  
-strings must be prefixed with the letter ``b``. In order to enable the same
39  
-behavior in Python 2, every module must import ``unicode_literals`` from
40  
-``__future__``::
  31
+In order to enable the same behavior in Python 2, every module must import
  32
+``unicode_literals`` from ``__future__``::
41 33
 
42 34
     from __future__ import unicode_literals
43 35
 
@@ -47,3 +39,84 @@ behavior in Python 2, every module must import ``unicode_literals`` from
47 39
 Be cautious if you have to `slice bytestrings`_.
48 40
 
49 41
 .. _slice bytestrings: http://docs.python.org/py3k/howto/pyporting.html#bytes-literals
  42
+
  43
+Exceptions
  44
+----------
  45
+
  46
+When you capture exceptions, use the ``as`` keyword::
  47
+
  48
+    try:
  49
+        ...
  50
+    except MyException as exc:
  51
+        ...
  52
+
  53
+This older syntax was removed in Python 3::
  54
+
  55
+    try:
  56
+        ...
  57
+    except MyException, exc:
  58
+        ...
  59
+
  60
+The syntax to reraise an exception with a different traceback also changed.
  61
+Use :func:`six.reraise`.
  62
+
  63
+
  64
+.. module: django.utils.six
  65
+
  66
+Writing compatible code with six
  67
+================================
  68
+
  69
+six is the canonical compatibility library for supporting Python 2 and 3 in
  70
+a single codebase. Read its `documentation <six>`_!
  71
+
  72
+:mod:`six` is bundled with Django: you can import it as :mod:`django.utils.six`.
  73
+
  74
+Here are the most common changes required to write compatible code.
  75
+
  76
+String types
  77
+------------
  78
+
  79
+The ``basestring`` and ``unicode`` types were removed in Python 3, and the
  80
+meaning of ``str`` changed. To test these types, use the following idioms::
  81
+
  82
+    isinstance(myvalue, six.string_types)       # replacement for basestring
  83
+    isinstance(myvalue, six.text_type)          # replacement for unicode
  84
+    isinstance(myvalue, bytes)                  # replacement for str
  85
+
  86
+Python ≥ 2.6 provides ``bytes`` as an alias for ``str``, so you don't need
  87
+:attr:`six.binary_type`.
  88
+
  89
+``long``
  90
+--------
  91
+
  92
+The ``long`` type no longer exists in Python 3. ``1L`` is a syntax error. Use
  93
+:data:`six.integer_types` check if a value is an integer or a long::
  94
+
  95
+    isinstance(myvalue, six.integer_types)      # replacement for (int, long)
  96
+
  97
+``xrange``
  98
+----------
  99
+
  100
+Import :func:`six.moves.xrange` wherever you use ``xrange``.
  101
+
  102
+Moved modules
  103
+-------------
  104
+
  105
+Some modules were renamed in Python 3. The :mod:`django.utils.six.moves
  106
+<six.moves>` module provides a compatible location to import them.
  107
+
  108
+In addition to six' defaults, Django's version provides ``dummy_thread`` as
  109
+``_dummy_thread``.
  110
+
  111
+PY3
  112
+---
  113
+
  114
+If you need different code in Python 2 and Python 3, check :data:`six.PY3`::
  115
+
  116
+    if six.PY3:
  117
+        # do stuff Python 3-wise
  118
+    else:
  119
+        # do stuff Python 2-wise
  120
+
  121
+This is a last resort solution when :mod:`six` doesn't provide an appropriate
  122
+function.

0 notes on commit 00ace01

Aymeric Augustin

I just fixed the link. Thanks!

Please sign in to comment.
Something went wrong with that request. Please try again.