1 files changed, 112 insertions, 0 deletions
diff --git a/FOSS/Python/Dependencies/future-0.18.2/docs/translation.rst b/FOSS/Python/Dependencies/future-0.18.2/docs/translation.rst
new file mode 100644
index 0000000..632c46b
--- /dev/null
+++ b/FOSS/Python/Dependencies/future-0.18.2/docs/translation.rst
@@ -0,0 +1,112 @@
+.. _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/>`_.