summaryrefslogtreecommitdiffstats
path: root/FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst
diff options
context:
space:
mode:
authoryum <yum.food.vr@gmail.com>2023-01-01 21:05:27 -0800
committeryum <yum.food.vr@gmail.com>2023-01-01 21:44:45 -0800
commite25bdba3a3a53b09be5269d8b065c13b73ab55c3 (patch)
tree1d1dc1d94cde92c2f4f8ce86017395054787515d /FOSS/Python/Dependencies/future-0.18.2/docs/imports.rst
parent0d408cc812a094a708edbe4baf536e928731cfc3 (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.rst126
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`.