Lines Matching refs:Python

4 Porting Python 2 Code to Python 3
11    With Python 3 being the future of Python while Python 2 is still in active
13    Python. This guide is meant to help you figure out how best to support both
14    Python 2 & 3 simultaneously.
16    If you are looking to port an extension module instead of pure Python code,
19    If you would like to read one core Python developer's take on why Python 3
20    came into existence, you can read Nick Coghlan's `Python 3 Q & A`_ or
21    Brett Cannon's `Why Python 3 exists`_.
29 To make your project be single-source Python 2/3 compatible, the basic steps
32 #. Only worry about supporting Python 2.7
35 #. Learn the differences between Python 2 & 3
37 #. Use Pylint_ to help make sure you don't regress on your Python 3 support
40    use of Python 3 (``python -m pip install caniusepython3``)
42    to make sure you stay compatible with Python 2 & 3 (tox_ can help test
43    against multiple versions of Python; ``python -m pip install tox``)
45    works in both Python 2 & 3 (e.g. use mypy_ to check your typing under both
46    Python 2 & Python 3; ``python -m pip install mypy``).
51    is the one installed for the Python currently in use, whether it be
58 A key point about supporting Python 2 & 3 simultaneously is that you can start
59 **today**! Even if your dependencies are not supporting Python 3 yet that does
60 not mean you can't modernize your code **now** to support Python 3. Most changes
61 required to support Python 3 lead to cleaner code using newer practices even in
62 Python 2 code.
64 Another key point is that modernizing your Python 2 code to also support
65 Python 3 is largely automated for you. While you might have to make some API
66 decisions thanks to Python 3 clarifying text data versus binary data, the
71 your code to support Python 2 & 3 simultaneously.
74 Drop support for Python 2.6 and older
77 While you can make Python 2.5 work with Python 3, it is **much** easier if you
78 only have to work with Python 2.7. If dropping Python 2.5 is not an
79 option then the six_ project can help you support Python 2.5 & 3 simultaneously
83 If you are able to skip Python 2.5 and older, then the required changes
84 to your code should continue to look and feel like idiomatic Python code. At
89 But you should aim for only supporting Python 2.7. Python 2.6 is no longer
91 to work around any issues you come across with Python 2.6. There are also some
92 tools mentioned in this HOWTO which do not support Python 2.6 (e.g., Pylint_),
94 for you if you only support the versions of Python that you have to support.
101 specifying what versions of Python you support. As your project does not support
102 Python 3 yet you should at least have
103 ``Programming Language :: Python :: 2 :: Only`` specified. Ideally you should
104 also specify each major/minor version of Python that you do support, e.g.
105 ``Programming Language :: Python :: 2.7``.
111 Once you have your code supporting the oldest version of Python 2 you want it
121 Learn the differences between Python 2 & 3
125 Python 3! But to fully understand how your code is going to change and what
127 Python 3 makes in terms of Python 2. Typically the two best ways of doing that
128 is reading the :ref:`"What's New" <whatsnew-index>` doc for each release of Python 3 and the
129 `Porting to Python 3`_ book (which is free online). There is also a handy
130 `cheat sheet`_ from the Python-Future project.
136 Once you feel like you know what is different in Python 3 compared to Python 2,
139 depend on how much like Python 3 you want your code to be. Futurize_ does its
140 best to make Python 3 idioms and practices exist in Python 2, e.g. backporting
141 the ``bytes`` type from Python 3 so that you have semantic parity between the
142 major versions of Python. Modernize_,
143 on the other hand, is more conservative and targets a Python 2/3 subset of
144 Python, directly relying on six_ to help provide compatibility. As Python 3 is
146 practices that Python 3 introduces which you are not accustomed to yet.
149 Python 3 while staying compatible with the version of Python 2 you started with.
157 Python 3 and so there are a handful of things you will need to update manually
158 to get full Python 3 support (which of these steps are necessary vary between
170 In Python 3, ``5 / 2 == 2.5`` and not ``2``; all division between ``int`` values
171 result in a ``float``. This change has actually been planned since Python 2.2
191 In Python 2 you could use the ``str`` type for both text and binary data.
201 pronounced, Python 3 did what most languages created in the age of the internet
203 mixed together (Python predates widespread access to the internet). For any code
212 do well). In Python 2 this means making sure the APIs that take text can work
214 ``bytes`` type from Python 3 (which is a subset of ``str`` in Python 2 and acts
215 as an alias for ``bytes`` type in Python 2). Usually the biggest issue is
216 realizing which methods exist on which types in Python 2 & 3 simultaneously
217 (for text that's ``unicode`` in Python 2 and ``str`` in Python 3, for binary
218 that's ``str``/``bytes`` in Python 2 and ``bytes`` in Python 3). The following
219 table lists the **unique** methods of each data type across Python 2 & 3
221 either Python 2 or 3, but it can't be used by the textual data type consistently
222 between Python 2 and 3 because ``str`` in Python 3 doesn't have the method). Do
223 note that as of Python 3.5 the ``__mod__`` method was added to the bytes type.
256 binary reading).  Under Python 3, binary files and text files are clearly
262 module is consistent from Python 2 to 3 while the built-in :func:`open` function
263 is not (in Python 3 it's actually :func:`io.open`). Do not bother with the
265 keeping compatibility with Python 2.5.
268 same arguments between Python 2 & 3. Passing an integer to ``bytes`` in Python 2
270 But in Python 3, an integer argument to ``bytes`` will give you a bytes object
273 bytes object to ``str``. In Python 2 you just get the bytes object back:
274 ``str(b'3') == b'3'``. But in Python 3 you get the string representation of the
278 **not** require any special handling). In Python 2,
279 ``b'123'[1] == b'2'`` while in Python 3 ``b'123'[1] == 50``. Because binary data
280 is simply a collection of binary numbers, Python 3 returns the integer value for
281 the byte you index on. But in Python 2 because ``bytes == str``, indexing
283 named ``six.indexbytes()`` which will return an integer like in Python 3:
290    code for binary data works with ``bytes`` in Python 2 (see the table above
305 version of Python is running. The best way to do this is with feature detection
306 of whether the version of Python you're running under supports what you need.
308 against Python 2 and not Python 3. To help explain this, let's look at an
312 is available in Python's standard library since Python 3.3 and available for
313 Python 2 through importlib2_ on PyPI. You might be tempted to write code to
323 The problem with this code is what happens when Python 4 comes out? It would
324 be better to treat Python 2 as the exceptional case instead of Python 3 and
325 assume that future Python versions will be more compatible with Python 3 than
326 Python 2::
348 Once you have fully translated your code to be compatible with Python 3, you
350 Python 3. This is especially true if you have a dependency which is blocking you
351 from actually running under Python 3 at the moment.
360 You can also run Python 2 with the ``-3`` flag to be warned about various
366 to receive warnings when your code begins to deviate from Python 3
369 you only support Python 2.7 and Python 3.4 or newer as that is Pylint's
370 minimum Python version support.
376 **After** you have made your code compatible with Python 3 you should begin to
379 -- directly or indirectly -- are blocking you from supporting Python 3. There
385 you from using Python 3. This allows you to avoid having to manually check your
386 dependencies and to be notified quickly when you can start running on Python 3.
389 Update your ``setup.py`` file to denote Python 3 compatibility
392 Once your code works under Python 3, you should update the classifiers in
393 your ``setup.py`` to contain ``Programming Language :: Python :: 3`` and to not
394 specify sole Python 2 support. This will tell anyone using your code that you
395 support Python 2 **and** 3. Ideally you will also want to add classifiers for
396 each major/minor version of Python you now support.
402 Once you are able to fully run under Python 3 you will want to make sure your
403 code always works under both Python 2 & 3. Probably the best tool for running
404 your tests under multiple Python interpreters is tox_. You can then integrate
406 Python 2 or 3 support.
408 You may also want to use the ``-bb`` flag with the Python 3 interpreter to
410 (the latter is available starting in Python 3.5). By default type-differing
417 Python 2 and 3 simultaneously. Your testing will also be set up so that you
418 don't accidentally break Python 2 or 3 compatibility regardless of which version
427 if it's being run under Python 2, then you can run the tool a second time as if
428 your code is running under Python 3. By running a static type checker twice like
430 of Python compared to another. If you add optional type hints to your code you
432 to make sure everything functions as expected in both versions of Python.
442 .. _Porting to Python 3: http://python3porting.com/
454 .. _Why Python 3 exists: https://snarky.ca/why-python-3-exists