diff options
| author | yum <yum.food.vr@gmail.com> | 2023-01-23 14:28:53 -0800 |
|---|---|---|
| committer | yum <yum.food.vr@gmail.com> | 2023-01-23 14:32:09 -0800 |
| commit | 9fff496394dcd94c4084694ca96a5e07ab836274 (patch) | |
| tree | d89b78e16ecb6011bdd74555da79f7a8c1d90752 /FOSS/Python/Dependencies/future-0.18.2/docs/faq.rst | |
| parent | 9329d64f991b8b3289af22e4c2eedb09a97c5640 (diff) | |
package.ps1 now fetches all dependencies
Don't literally check in Python since it looks dodgy (rightfully so).
Instead the build script just fetches it.
* Update README, simplifying language and documenting other projects
Diffstat (limited to 'FOSS/Python/Dependencies/future-0.18.2/docs/faq.rst')
| -rw-r--r-- | FOSS/Python/Dependencies/future-0.18.2/docs/faq.rst | 310 |
1 files changed, 0 insertions, 310 deletions
diff --git a/FOSS/Python/Dependencies/future-0.18.2/docs/faq.rst b/FOSS/Python/Dependencies/future-0.18.2/docs/faq.rst deleted file mode 100644 index 9b1eab0..0000000 --- a/FOSS/Python/Dependencies/future-0.18.2/docs/faq.rst +++ /dev/null @@ -1,310 +0,0 @@ -Frequently Asked Questions (FAQ) -******************************** - -Who is this for? -================ - -1. People with existing or new Python 3 codebases who wish to provide -ongoing Python 2.7 support easily and with little maintenance burden. - -2. People who wish to ease and accelerate migration of their Python 2 codebases -to Python 3.4+, module by module, without giving up Python 2 compatibility. - - -Why upgrade to Python 3? -======================== - -.. epigraph:: - - "Python 2 is the next COBOL." - - -- Alex Gaynor, at PyCon AU 2013 - -Python 2.7 is the end of the Python 2 line. (See `PEP 404 -<http://www.python.org/peps/pep-0404/>`_.) The language and standard -libraries are improving only in Python 3.x. - -Python 3.x is a better language and better set of standard libraries than -Python 2.x in many ways. Python 3.x is cleaner, less warty, and easier to -learn than Python 2. It has better memory efficiency, easier Unicode handling, -and powerful new features like the `asyncio -<https://docs.python.org/3/library/asyncio.html>`_ module. - -.. Unicode handling is also much easier. For example, see `this page -.. <http://pythonhosted.org/kitchen/unicode-frustrations.html>`_ -.. describing some of the problems with handling Unicode on Python 2 that -.. Python 3 mostly solves. - - -Porting philosophy -================== - -Why write Python 3-style code? ------------------------------- - -Here are some quotes: - -- "Django's developers have found that attempting to write Python 3 code - that's compatible with Python 2 is much more rewarding than the - opposite." from the `Django docs - <https://docs.djangoproject.com/en/dev/topics/python3/>`_. - -- "Thanks to Python 3 being more strict about things than Python 2 (e.g., - bytes vs. strings), the source translation [from Python 3 to 2] can be - easier and more straightforward than from Python 2 to 3. Plus it gives - you more direct experience developing in Python 3 which, since it is - the future of Python, is a good thing long-term." from the official - guide `"Porting Python 2 Code to Python 3" - <http://docs.python.org/2/howto/pyporting.html>`_ by Brett Cannon. - -- "Developer energy should be reserved for addressing real technical - difficulties associated with the Python 3 transition (like - distinguishing their 8-bit text strings from their binary data). They - shouldn't be punished with additional code changes ..." from `PEP 414 - <http://www.python.org/dev/peps/pep-0414/>`_ by Armin Ronacher and Nick - Coghlan. - - -Can't I just roll my own Py2/3 compatibility layer? ---------------------------------------------------- - -Yes, but using ``python-future`` will probably be easier and lead to cleaner -code with fewer bugs. - -Consider this quote: - -.. epigraph:: - - "Duplication of effort is wasteful, and replacing the various - home-grown approaches with a standard feature usually ends up making - things more readable, and interoperable as well." - - -- Guido van Rossum (`blog post <http://www.artima.com/weblogs/viewpost.jsp?thread=86641>`_) - - -``future`` also includes various Py2/3 compatibility tools in -:mod:`future.utils` picked from large projects (including IPython, -Django, Jinja2, Pandas), which should reduce the burden on every project to -roll its own py3k compatibility wrapper module. - - -What inspired this project? ---------------------------- - -In our Python training courses, we at `Python Charmers -<http://pythoncharmers.com>`_ faced a dilemma: teach people Python 3, which was -future-proof but not as useful to them today because of weaker 3rd-party -package support, or teach people Python 2, which was more useful today but -would require them to change their code and unlearn various habits soon. We -searched for ways to avoid polluting the world with more deprecated code, but -didn't find a good way. - -Also, in attempting to help with porting packages such as `scikit-learn -<http://scikit-learn.org>`_ to Python 3, I (Ed) was dissatisfied with how much -code cruft was necessary to introduce to support Python 2 and 3 from a single -codebase (the preferred porting option). Since backward-compatibility with -Python 2 may be necessary for at least the next 5 years, one of the promised -benefits of Python 3 -- cleaner code with fewer of Python 2's warts -- was -difficult to realize before in practice in a single codebase that supported -both platforms. - -The goal is to accelerate the uptake of Python 3 and help the strong Python -community to remain united around a single version of the language. - - -Maturity -======== - -How well has it been tested? ----------------------------- - -``future`` is used by several major projects, including `mezzanine -<http://mezzanine.jupo.org>`_ and `ObsPy <http://www.obspy.org>`_. It is also -currently being used to help with porting 800,000 lines of Python 2 code in -`Sage <http://sagemath.org>`_ to Python 2/3. - -Currently ``python-future`` has over 1000 unit tests. Many of these are straight -from the Python 3.3 and 3.4 test suites. - -In general, the ``future`` package itself is in good shape, whereas the -``futurize`` script for automatic porting is imperfect; chances are it will -require some manual cleanup afterwards. The ``past`` package also needs to be -expanded. - - -Is the API stable? ------------------- - -Not yet; ``future`` is still in beta. Where possible, we will try not to break -anything which was documented and used to work. After version 1.0 is released, -the API will not change in backward-incompatible ways until a hypothetical -version 2.0. - -.. - Are there any example of Python 2 packages ported to Python 3 using ``future`` and ``futurize``? - ------------------------------------------------------------------------------------------------ - - Yes, an example is the port of ``xlwt``, available `here - <https://github.com/python-excel/xlwt/pull/32>`_. - - The code also contains backports for several Py3 standard library - modules under ``future/standard_library/``. - - -Relationship between python-future and other compatibility tools -================================================================ - -How does this relate to ``2to3``? ---------------------------------- - -``2to3`` is a powerful and flexible tool that can produce different -styles of Python 3 code. It is, however, primarily designed for one-way -porting efforts, for projects that can leave behind Python 2 support. - -The example at the top of the `2to3 docs -<http://docs.python.org/2/library/2to3.html>`_ demonstrates this. After -transformation by ``2to3``, ``example.py`` looks like this:: - - def greet(name): - print("Hello, {0}!".format(name)) - print("What's your name?") - name = input() - greet(name) - -This is Python 3 code that, although syntactically valid on Python 2, -is semantically incorrect. On Python 2, it raises an exception for -most inputs; worse, it allows arbitrary code execution by the user -for specially crafted inputs because of the ``eval()`` executed by Python -2's ``input()`` function. - -This is not an isolated example; almost every output of ``2to3`` will need -modification to provide backward compatibility with Python 2. As an -alternative, the ``python-future`` project provides a script called -``futurize`` that is based on ``lib2to3`` but will produce code that is -compatible with both platforms (Py2 and Py3). - - -Can I maintain a Python 2 codebase and use 2to3 to automatically convert to Python 3 in the setup script? ---------------------------------------------------------------------------------------------------------- - -This was originally the approach recommended by Python's core developers, -but it has some large drawbacks: - -1. First, your actual working codebase will be stuck with Python 2's -warts and smaller feature set for as long as you need to retain Python 2 -compatibility. This may be at least 5 years for many projects, possibly -much longer. - -2. Second, this approach carries the significant disadvantage that you -cannot apply patches submitted by Python 3 users against the -auto-generated Python 3 code. (See `this talk -<http://www.youtube.com/watch?v=xNZ4OVO2Z_E>`_ by Jacob Kaplan-Moss.) - - -What is the relationship between ``future`` and ``six``? --------------------------------------------------------- - -``python-future`` is a higher-level compatibility layer than ``six`` that -includes more backported functionality from Python 3, more forward-ported -functionality from Python 2, and supports cleaner code, but requires more -modern Python versions to run. - -``python-future`` and ``six`` share the same goal of making it possible to write -a single-source codebase that works on both Python 2 and Python 3. -``python-future`` has the further goal of allowing standard Py3 code to run with -almost no modification on both Py3 and Py2. ``future`` provides a more -complete set of support for Python 3's features, including backports of -Python 3 builtins such as the ``bytes`` object (which is very different -to Python 2's ``str`` object) and several standard library modules. - -``python-future`` supports only Python 2.7+ and Python 3.4+, whereas ``six`` -supports all versions of Python from 2.4 onwards. (See -:ref:`supported-versions`.) If you must support older Python versions, -``six`` will be essential for you. However, beware that maintaining -single-source compatibility with older Python versions is ugly and `not -fun <http://lucumr.pocoo.org/2013/5/21/porting-to-python-3-redux/>`_. - -If you can drop support for older Python versions, ``python-future`` leverages -some important features introduced into Python 2.7, such as -import hooks, and a comprehensive and well-tested set of backported -functionality, to allow you to write more idiomatic, maintainable code with -fewer compatibility hacks. - - -What is the relationship between ``python-future`` and ``python-modernize``? ----------------------------------------------------------------------------- - -``python-future`` contains, in addition to the ``future`` compatibility -package, a ``futurize`` script that is similar to ``python-modernize.py`` -in intent and design. Both are based heavily on ``2to3``. - -Whereas ``python-modernize`` converts Py2 code into a common subset of -Python 2 and 3, with ``six`` as a run-time dependency, ``futurize`` -converts either Py2 or Py3 code into (almost) standard Python 3 code, -with ``future`` as a run-time dependency. - -Because ``future`` provides more backported Py3 behaviours from ``six``, -the code resulting from ``futurize`` is more likely to work -identically on both Py3 and Py2 with less additional manual porting -effort. - - -Platform and version support -============================ - -.. _supported-versions: - -Which versions of Python does ``python-future`` support? --------------------------------------------------------- - -Python 2.7, and 3.4+ only. - -Python 2.7 introduced many important forward-compatibility -features (such as import hooks, ``b'...'`` literals and ``__future__`` -definitions) that greatly reduce the maintenance burden for single-source -Py2/3 compatible code. ``future`` leverages these features and aims to -close the remaining gap between Python 3 and 2.7. - - -Do you support Pypy? -~~~~~~~~~~~~~~~~~~~~ - -Yes, except for the standard library import hooks (currently). Feedback -and pull requests are welcome! - - -Do you support IronPython and/or Jython? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Not sure. This would be nice... - - -.. _support: - -Support -======= - -Is there a mailing list? ------------------------- - -Yes, please ask any questions on the `python-porting -<https://mail.python.org/mailman/listinfo/python-porting>`_ mailing list. - - -.. _contributing: - -Contributing -============ - -Can I help? ------------ - -Yes please :) We welcome bug reports, additional tests, pull requests, -and stories of either success or failure with using it. Help with the fixers -for the ``futurize`` script is particularly welcome. - - -Where is the repo? ------------------- - -`<https://github.com/PythonCharmers/python-future>`_. |
