Dev: Py3compat module

The IPython.utils.py3compat module provides a number of functions to make it easier to write code for Python 2 and 3. We also use 2to3 in the setup process to change syntax, and the io.open() function, which is essentially the built in open function from Python 3.

The names provided are:

• PY3: True in Python 3, False in Python 2.

Unicode related

• decode, encode: Shortcuts to decode or encode strings, using sys.stdin.encoding by default, and using replacement characters on errors.
• str_to_unicode, unicode_to_str, str_to_bytes, bytes_to_str: Convert to/from the platform's standard str type (bytes in Python 2, unicode in Python 3). Each function is a no-op on one of the two platforms.
• cast_unicode, cast_bytes: Accept unknown unicode or byte strings, and convert them accordingly.
• cast_bytes_py2: Casts unicode to byte strings on Python 2, but doesn't do anything on Python 3.

Miscellaneous

• input: Refers to raw_input on Python 2, input on Python 3 (needed because 2to3 only converts calls to raw_input, not assignments to other names).
• builtin_mod_name: The string name you import to get the builtins (__builtin__ --> builtins).
• isidentifier: Checks if a string is a valid Python identifier.
• open: Simple wrapper for Python 3 unicode-enabled open. Similar to codecs.open, but allows universal newlines. The current implementation only supports the very simplest use.
• MethodType: types.MethodType from Python 3. Takes only two arguments: function, instance. The class argument for Python 2 is filled automatically.
• doctest_refactor_print: Can be called on a string or a function (or used as a decorator). In Python 3, it converts print statements in doctests to print() calls. 2to3 does this for real doctests, but we need it in several other places. It simply uses a regex, which is good enough for the current cases.
• u_format: Where tests use the repr() of a unicode string, it should be written '{u}"thestring"', and fed to this function, which will produce 'u"thestring"' for Python 2, and '"thestring"' for Python 3. Can also be used as a decorator, to work on a docstring.
• execfile: Makes a return on Python 3 (where it's no longer a builtin), and upgraded to handle Unicode filenames on Python 2.