113 lines
3.7 KiB
ReStructuredText
113 lines
3.7 KiB
ReStructuredText
.. _translation:
|
|
|
|
Using Python 2-only dependencies on Python 3
|
|
--------------------------------------------
|
|
|
|
The ``past`` module provides an experimental ``translation`` package to help
|
|
with importing and using old Python 2 modules in a Python 3 environment.
|
|
|
|
This is implemented using PEP 414 import hooks together with fixers from
|
|
``lib2to3`` and ``libfuturize`` (included with ``python-future``) that
|
|
attempt to automatically translate Python 2 code to Python 3 code with equivalent
|
|
semantics upon import.
|
|
|
|
*Note* This feature is still in alpha and needs further development to support a
|
|
full range of real-world Python 2 modules. Also be aware that the API for
|
|
this package might change considerably in later versions.
|
|
|
|
Here is how to use it::
|
|
|
|
$ pip3 install plotrique==0.2.5-7 --no-compile # to ignore SyntaxErrors
|
|
$ python3
|
|
|
|
Then pass in a whitelist of module name prefixes to the
|
|
``past.translation.autotranslate()`` function. Example::
|
|
|
|
>>> from past.translation import autotranslate
|
|
>>> autotranslate(['plotrique'])
|
|
>>> import plotrique
|
|
|
|
Here is another example::
|
|
|
|
>>> from past.translation import install_hooks, remove_hooks
|
|
>>> install_hooks(['mypy2module'])
|
|
>>> import mypy2module
|
|
>>> remove_hooks()
|
|
|
|
This will translate, import and run Python 2 code such as the following::
|
|
|
|
### File: mypy2module.py
|
|
|
|
# Print statements are translated transparently to functions:
|
|
print 'Hello from a print statement'
|
|
|
|
# xrange() is translated to Py3's range():
|
|
total = 0
|
|
for i in xrange(10):
|
|
total += i
|
|
print 'Total is: %d' % total
|
|
|
|
# Dictionary methods like .keys() and .items() are supported and
|
|
# return lists as on Python 2:
|
|
d = {'a': 1, 'b': 2}
|
|
assert d.keys() == ['a', 'b']
|
|
assert isinstance(d.items(), list)
|
|
|
|
# Functions like range, reduce, map, filter also return lists:
|
|
assert isinstance(range(10), list)
|
|
|
|
# The exec statement is supported:
|
|
exec 'total += 1'
|
|
print 'Total is now: %d' % total
|
|
|
|
# Long integers are supported:
|
|
k = 1234983424324L
|
|
print 'k + 1 = %d' % k
|
|
|
|
# Most renamed standard library modules are supported:
|
|
import ConfigParser
|
|
import HTMLParser
|
|
import urllib
|
|
|
|
|
|
The attributes of the module are then accessible normally from Python 3.
|
|
For example::
|
|
|
|
# This Python 3 code works
|
|
>>> type(mypy2module.d)
|
|
builtins.dict
|
|
|
|
This is a standard Python 3 data type, so, when called from Python 3 code,
|
|
``keys()`` returns a view, not a list::
|
|
|
|
>>> type(mypy2module.d.keys())
|
|
builtins.dict_keys
|
|
|
|
|
|
.. _translation-limitations:
|
|
|
|
Known limitations of ``past.translation``
|
|
*****************************************
|
|
|
|
- It currently requires a newline at the end of the module or it throws a
|
|
``ParseError``.
|
|
|
|
- This only works with pure-Python modules. C extension modules and Cython code
|
|
are not supported.
|
|
|
|
- The biggest hurdle to automatic translation is likely to be ambiguity
|
|
about byte-strings and text (unicode strings) in the Python 2 code. If the
|
|
``past.autotranslate`` feature fails because of this, you could try
|
|
running ``futurize`` over the code and adding a ``b''`` or ``u''`` prefix to
|
|
the relevant string literals. To convert between byte-strings and text (unicode
|
|
strings), add an ``.encode`` or ``.decode`` method call. If this succeeds,
|
|
please push your patches upstream to the package maintainers.
|
|
|
|
- Otherwise, the source translation feature offered by the ``past.translation``
|
|
package has similar limitations to the ``futurize`` script (see
|
|
:ref:`futurize-limitations`). Help developing and testing this feature further
|
|
would be particularly welcome.
|
|
|
|
Please report any bugs you find on the ``python-future`` `bug tracker
|
|
<https://github.com/PythonCharmers/python-future/>`_.
|