Adds documentation for the new Windows embedded package.

Author: zooba

Doc/using/windows.rst

@@ -42,9 +42,11 @@ After starting the installer, one of two options may be selected:
 If you select "Install Now":
 
 * You will *not* need to be an administrator (unless a system update for the
-  C Runtime Library is required)
+  C Runtime Library is required or you install the :ref:`launcher` for all
+  users)
 * Python will be installed into your user directory
-* The :ref:`launcher` will *also* be installed into your user directory
+* The :ref:`launcher` will be installed according to the option at the bottom
+  of the first pace
 * The standard library, test suite, launcher and pip will be installed
 * If selected, the install directory will be added to your :envvar:`PATH`
 * Shortcuts will only be visible for the current user
@@ -60,7 +62,7 @@ installation". In this case:
 * Python will be installed into the Program Files directory
 * The :ref:`launcher` will be installed into the Windows directory
 * Optional features may be selected during installation
-* The standard library will be pre-compiled to bytecode
+* The standard library can be pre-compiled to bytecode
 * If selected, the install directory will be added to the system :envvar:`PATH`
 * Shortcuts are available for all users
 
@@ -649,6 +651,8 @@ target Python.
 
 
 
+.. finding_modules:
+
 Finding modules
 ===============
 
@@ -718,6 +722,8 @@ following advice will prevent conflicts with other installations:
 * Include a ``pyvenv.cfg`` file alongside your executable containing
   ``applocal = true``. This will ensure that your own directory will be used to
   resolve paths even if you have included the standard library in a ZIP file.
+  It will also ignore user site-packages and other paths listed in the
+  registry.
 
 * If you are loading :file:`python3.dll` or :file:`python35.dll` in your own
   executable, explicitly call :c:func:`Py_SetPath` or (at least)
@@ -733,7 +739,9 @@ following advice will prevent conflicts with other installations:
 
 These will ensure that the files in a system-wide installation will not take
 precedence over the copy of the standard library bundled with your application.
-Otherwise, your users may experience problems using your application.
+Otherwise, your users may experience problems using your application. Note that
+the first suggestion is the best, as the other may still be susceptible to
+non-standard paths in the registry and user site-packages.
 
 Additional modules
 ==================
@@ -822,6 +830,83 @@ For extension modules, consult :ref:`building-on-windows`.
       by Trent Apted et al, 2007
 
 
+Embedded Distribution
+=====================
+
+.. versionadded:: 3.5
+
+The embedded distribution is a ZIP file containing a minimal Python environment.
+It is intended for acting as part of another application, rather than being
+directly accessed by end-users.
+
+When extracted, the embedded distribution is (almost) fully isolated from the
+user's system, including environment variables, system registry settings, and
+installed packages. The standard library is included as pre-compiled and
+optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python35.dll``,
+``python.exe`` and ``pythonw.exe`` are all provided. Tcl/tk (including all
+dependants, such as Idle), pip and the Python documentation are not included.
+
+.. note::
+
+    The embedded distribution does not include the `Microsoft C Runtime
+    <http://www.microsoft.com/en-us/download/details.aspx?id=48145>`_ and it is
+    the responsibility of the application installer to provide this. The
+    runtime may have already been installed on a user's system previously or
+    automatically via Windows Update, and can be detected by finding
+    ``ucrtbase.dll`` in the system directory.
+
+Third-party packages should be installed by the application installer alongside
+the embedded distribution. Using pip to manage dependencies as for a regular
+Python installation is not supported with this distribution, though with some
+care it may be possible to include and use pip for automatic updates. In
+general, third-party packages should be treated as part of the application
+("vendoring") so that the developer can ensure compatibility with newer
+versions before providing updates to users.
+
+The two recommended use cases for this distribution are described below.
+
+Python Application
+------------------
+
+An application written in Python does not necessarily require users to be aware
+of that fact. The embedded distribution may be used in this case to include a
+private version of Python in an install package. Depending on how transparent it
+should be (or conversely, how professional it should appear), there are two
+options.
+
+Using a specialized executable as a launcher requires some coding, but provides
+the most transparent experience for users. With a customized launcher, there are
+no obvious indications that the program is running on Python: icons can be
+customized, company and version information can be specified, and file
+associations behave properly. In most cases, a custom launcher should simply be
+able to call ``Py_Main`` with a hard-coded command line.
+
+The simpler approach is to provide a batch file or generated shortcut that
+directly calls the ``python.exe`` or ``pythonw.exe`` with the required
+command-line arguments. In this case, the application will appear to be Python
+and not its actual name, and users may have trouble distinguishing it from other
+running Python processes or file associations.
+
+With the latter approach, packages should be installed as directories alongside
+the Python executable to ensure they are available on the path. With the
+specialized launcher, packages can be located in other locations as there is an
+opportunity to specify the search path before launching the application.
+
+Embedding Python
+----------------
+
+Applications written in native code often require some form of scripting
+language, and the embedded Python distribution can be used for this purpose. In
+general, the majority of the application is in native code, and some part will
+either invoke ``python.exe`` or directly use ``python3.dll``. For either case,
+extracting the embedded distribution to a subdirectory of the application
+installation is sufficient to provide a loadable Python interpreter.
+
+As with the application use, packages can be installed to any location as there
+is an opportunity to specify search paths before initializing the interpreter.
+Otherwise, there is no fundamental differences between using the embedded
+distribution and a regular installation.
+
 Other resources
 ===============