diff options
| author | yum <yum.food.vr@gmail.com> | 2023-01-01 21:05:27 -0800 |
|---|---|---|
| committer | yum <yum.food.vr@gmail.com> | 2023-01-01 21:44:45 -0800 |
| commit | e25bdba3a3a53b09be5269d8b065c13b73ab55c3 (patch) | |
| tree | 1d1dc1d94cde92c2f4f8ce86017395054787515d /FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst | |
| parent | 0d408cc812a094a708edbe4baf536e928731cfc3 (diff) | |
Embed git in package
package.ps1 fetches PortableGit and embeds it in the package. This
eliminates all but one runtime dependency (MSVC++ Redistributable).
* Move Python into a new FOSS folder.
Diffstat (limited to 'FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst')
| -rw-r--r-- | FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst | 126 |
1 files changed, 126 insertions, 0 deletions
diff --git a/FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst b/FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst new file mode 100644 index 0000000..f7dcd9f --- /dev/null +++ b/FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst @@ -0,0 +1,126 @@ +.. _imports: + +Imports +======= + +.. _-__future__-imports: + +__future__ imports +------------------ + +To write a Python 2/3 compatible codebase, the first step is to add this line +to the top of each module:: + + from __future__ import absolute_import, division, print_function + +For guidelines about whether to import ``unicode_literals`` too, see below +(:ref:`unicode-literals`). + +For more information about the ``__future__`` imports, which are a +standard feature of Python, see the following docs: + +- absolute_import: `PEP 328: Imports: Multi-Line and Absolute/Relative <http://www.python.org/dev/peps/pep-0328>`_ +- division: `PEP 238: Changing the Division Operator <http://www.python.org/dev/peps/pep-0238>`_ +- print_function: `PEP 3105: Make print a function <http://www.python.org/dev/peps/pep-3105>`_ +- unicode_literals: `PEP 3112: Bytes literals in Python 3000 <http://www.python.org/dev/peps/pep-3112>`_ + +These are all available in Python 2.7 and up, and enabled by default in Python 3.x. + + +.. _builtins-imports: + +Imports of builtins +------------------- + +.. _star-imports: + +Implicit imports +~~~~~~~~~~~~~~~~ + +If you don't mind namespace pollution, the easiest way to provide Py2/3 +compatibility for new code using ``future`` is to include the following imports +at the top of every module:: + + from builtins import * + +On Python 3, this has no effect. (It shadows builtins with globals of the same +names.) + +On Python 2, this import line shadows 18 builtins (listed below) to +provide their Python 3 semantics. + + +.. _explicit-imports: + +Explicit imports +~~~~~~~~~~~~~~~~ + +Explicit forms of the imports are often preferred and are necessary for using +certain automated code-analysis tools. + +The complete set of imports of builtins from ``future`` is:: + + from builtins import (ascii, bytes, chr, dict, filter, hex, input, + int, map, next, oct, open, pow, range, round, + str, super, zip) + +These are also available under the ``future.builtins`` namespace for backward compatibility. + +Importing only some of the builtins is cleaner but increases the risk of +introducing Py2/3 portability bugs as your code evolves over time. For example, +be aware of forgetting to import ``input``, which could expose a security +vulnerability on Python 2 if Python 3's semantics are expected. + +.. One further technical distinction is that unlike the ``import *`` form above, +.. these explicit imports do actually modify ``locals()`` on Py3; this is +.. equivalent to typing ``bytes = bytes; int = int`` etc. for each builtin. + +The internal API is currently as follows:: + + from future.types import bytes, dict, int, range, str + from future.builtins.misc import (ascii, chr, hex, input, next, + oct, open, pow, round, super) + from future.builtins.iterators import filter, map, zip + +Please note that this internal API is evolving and may not be stable between +different versions of ``future``. To understand the details of the backported +builtins on Python 2, see the docs for these modules. + +For more information on what the backported types provide, see :ref:`what-else`. + +.. < Section about past.translation is included here > + + +.. _obsolete-builtins: + +Obsolete Python 2 builtins +__________________________ + +Twelve Python 2 builtins have been removed from Python 3. To aid with +porting code to Python 3 module by module, you can use the following +import to cause a ``NameError`` exception to be raised on Python 2 when any +of the obsolete builtins is used, just as would occur on Python 3:: + + from future.builtins.disabled import * + +This is equivalent to:: + + from future.builtins.disabled import (apply, cmp, coerce, execfile, + file, long, raw_input, reduce, reload, + unicode, xrange, StandardError) + +Running ``futurize`` over code that uses these Python 2 builtins does not +import the disabled versions; instead, it replaces them with their +equivalent Python 3 forms and then adds ``future`` imports to resurrect +Python 2 support, as described in :ref:`forwards-conversion-stage2`. + + +.. include:: standard_library_imports.rst + +.. include:: translation.rst + +.. include:: unicode_literals.rst + +Next steps +---------- +See :ref:`what-else`. |
