.. This file is part of Sympathy for Data.
..
.. Copyright (c) 2017 System Engineering Software Society
..
.. Sympathy for Data is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. Sympathy for Data is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
.. You should have received a copy of the GNU General Public License
.. along with Sympathy for Data. If not, see .
.. _python3:
Using and supporting Python 3
=============================
In version 1.4.0 we are introducing support for running Sympathy on Python 3.
It is entirely optional and Python 2 is also supported. Existing libraries
will continue to function when run on Python 2.
Python 3 is gaining more and more popularity and there are good reasons for
adapting Python 3 in new projects. Popular third party libraries have matured
and seem to work well in Python 3. Some newly developed packages may not support
Python 2 at all.
See `Python 2 or Python 3 `_ for
more reasons why you should use Python 3.
Python 3: differences compared to 2
-----------------------------------
The major difference between Python 2 and 3 is its handling of unicode (called
str in Python 3). In Python 3 you normally work with unicode for any kind of
text unless dealing with raw binary data.
Filenames are unicode in many cases where they were bytes (typically called
str in 2) in Python 2. Some examples:
.. code-block:: python
__file__
sys.path
os.environ
To get the corresponding unicode in Python 2:
.. code-block:: python
fs_encoding = sys.getfilesystemencoding()
__file__.decode(fs_encoding)
Dictionary methods key, values and items return view objects which can be
iterated but not indexed.
Some modules, functions and classes in the standard library have been renamed, for example:
.. code-block:: python
# Python 2
import Queue
import StringIO.StringIO
import os
os.getcwdu()
.. code-block:: python
# Python 3
import queue
import io.StringIO
import os
os.getcwd()
Python 2 and 3 compatbility
---------------------------
It is possible to write code that will run both Python 2 and 3.
While you need to support users on 2 this could be a good way to
move forward and is what we have done in Sympathy 1.4.0.
See `Porting to Python 3 `_
for more information.
Future imports
^^^^^^^^^^^^^^
To make Python 2 behave somewhat more like 3 you can use imports from the
__future__ module.
.. code-block:: python
from __future__ import print_function, division, unicode_literals, absolute_import
These need to appear at the top of your module.
Please read up on the details of what each of these do before you use them.
See `Future module `_ for
details.
IO module
^^^^^^^^^
The IO module contains a backport of the open(filename, ...) function from
Python 3.
Use io.open when working with text files.
See `IO module `_ for details.
Six package
^^^^^^^^^^^
Six is a third party package for writing code that is compatible with both
Python 2 and 3. It provides alternate names for the string types that can be
used in place of string, unicode and bytes. six.text_type returns unicode on
Python 2 and str on 3 and six.binary_type returns str on Python 2 and bytes on 3.
Alternate names for functions that have been renamed are available under six.moves.
See `Six package `_ for details.
String literals
^^^^^^^^^^^^^^^
String literals are unicode in Python 3 and normally binary in Python 2, unless
from __future__ import unicode_literals is used.
To force the type for string literals, use:
.. code-block:: python
b'hello' # Binary literal
u'hello' # Unicode literal
Python 3 only
-------------
If you don't need support for Python 2 there are many improvements that you
will benefit from if you start with 3.
Unicode handling! Many of the more advanced modules in the standard library have
been improved: subprocess, importlib, asyncio (not available in Python 2) to
name a few. Better handling of import loops and no need to repeat yourself when
using super().