translation.rst 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114
  1. .. _translation:
  2. Using Python 2-only dependencies on Python 3
  3. --------------------------------------------
  4. The ``past`` module provides an experimental ``translation`` package to help
  5. with importing and using old Python 2 modules in a Python 3 environment.
  6. This is implemented using PEP 414 import hooks together with fixers from
  7. ``lib2to3`` and ``libfuturize`` (included with ``python-future``) that
  8. attempt to automatically translate Python 2 code to Python 3 code with equivalent
  9. semantics upon import.
  10. *Note* This feature is still in alpha and needs further development to support a
  11. full range of real-world Python 2 modules. Also be aware that the API for
  12. this package might change considerably in later versions.
  13. Here is how to use it::
  14. $ pip3 install plotrique==0.2.5-7 --no-compile # to ignore SyntaxErrors
  15. $ python3
  16. Then pass in a whitelist of module name prefixes to the
  17. ``past.autotranslate()`` function. Example::
  18. >>> from past import autotranslate
  19. >>> autotranslate(['plotrique'])
  20. >>> import plotrique
  21. Here is another example::
  22. >>> from past.translation import install_hooks, remove_hooks
  23. >>> install_hooks(['mypy2module'])
  24. >>> import mypy2module
  25. >>> remove_hooks()
  26. This will translate, import and run Python 2 code such as the following::
  27. ### File: mypy2module.py
  28. # Print statements are translated transparently to functions:
  29. print 'Hello from a print statement'
  30. # xrange() is translated to Py3's range():
  31. total = 0
  32. for i in xrange(10):
  33. total += i
  34. print 'Total is: %d' % total
  35. # Dictionary methods like .keys() and .items() are supported and
  36. # return lists as on Python 2:
  37. d = {'a': 1, 'b': 2}
  38. assert d.keys() == ['a', 'b']
  39. assert isinstance(d.items(), list)
  40. # Functions like range, reduce, map, filter also return lists:
  41. assert isinstance(range(10), list)
  42. # The exec statement is supported:
  43. exec 'total += 1'
  44. print 'Total is now: %d' % total
  45. # Long integers are supported:
  46. k = 1234983424324L
  47. print 'k + 1 = %d' % k
  48. # Most renamed standard library modules are supported:
  49. import ConfigParser
  50. import HTMLParser
  51. import urllib
  52. The attributes of the module are then accessible normally from Python 3.
  53. For example::
  54. # This Python 3 code works
  55. >>> type(mypy2module.d)
  56. builtins.dict
  57. This is a standard Python 3 data type, so, when called from Python 3 code,
  58. ``keys()`` returns a view, not a list::
  59. >>> type(mypy2module.d.keys())
  60. builtins.dict_keys
  61. .. _translation-limitations:
  62. Known limitations of ``past.translation``
  63. *****************************************
  64. - It currently requires a newline at the end of the module or it throws a
  65. ``ParseError``.
  66. - This only works with pure-Python modules. C extension modules and Cython code
  67. are not supported.
  68. - The biggest hurdle to automatic translation is likely to be ambiguity
  69. about byte-strings and text (unicode strings) in the Python 2 code. If the
  70. ``past.autotranslate`` feature fails because of this, you could try
  71. running ``futurize`` over the code and adding a ``b''`` or ``u''`` prefix to
  72. the relevant string literals. To convert between byte-strings and text (unicode
  73. strings), add an ``.encode`` or ``.decode`` method call. If this succeeds,
  74. please push your patches upstream to the package maintainers.
  75. - Otherwise, the source translation feature offered by the ``past.translation``
  76. package has similar limitations to the ``futurize`` script (see
  77. :ref:`futurize-limitations`). Help developing and testing this feature further
  78. would be particularly welcome.
  79. Please report any bugs you find on the ``python-future`` `bug tracker
  80. <https://github.com/PythonCharmers/python-future/>`_.