.. This file is part of Sympathy for Data.
..
..  Copyright (c) 2017 Combine Control Systems AB
..
..     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 <http://www.gnu.org/licenses/>.


.. _python3:

Using and supporting Python 3
=============================

In version 1.4.0 we are introducing support for running Sympathy on Python 3.
The switch to Python 3 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 to 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 <https://wiki.python.org/moin/Python2orPython3>`_ for
more reasons why you should use Python 3.

Differences between Python 3 and Python 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, that is keys, 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 Python 3 compatibility
-----------------------------------

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 <https://docs.python.org/3/howto/pyporting.html>`_
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 <https://docs.python.org/2/library/__future__.html>`_ 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 <https://docs.python.org/2/library/io.html>`_ 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 in
Python 2 and str in 3 and six.binary_type returns str in Python 2 and bytes in 3.
Alternate names for functions that have been renamed are available under six.moves.
See `Six package <https://pythonhosted.org/six/>`_ 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 do not need support for Python 2 there are many improvements that you
will benefit from if you start with 3:

- Better unicode handling as mentioned.
- Many of the more advanced modules in the standard library have also been improved:
  subprocess, importlib, and asyncio (not available in Python 2) to name a few.
- Better handling of import loops and no need to repeat yourself when
  using super().