diff options
Diffstat (limited to 'Doc/using')
| -rw-r--r-- | Doc/using/cmdline.rst | 90 | ||||
| -rw-r--r-- | Doc/using/index.rst | 1 | ||||
| -rw-r--r-- | Doc/using/mac.rst | 6 | ||||
| -rw-r--r-- | Doc/using/scripts.rst | 12 | ||||
| -rw-r--r-- | Doc/using/venv-create.inc | 95 | ||||
| -rw-r--r-- | Doc/using/windows.rst | 135 |
6 files changed, 235 insertions, 104 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 57faf89e1a..75cb8ea24b 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -395,6 +395,8 @@ Miscellaneous options stored in a traceback of a trace. Use ``-X tracemalloc=NFRAME`` to start tracing with a traceback limit of *NFRAME* frames. See the :func:`tracemalloc.start` for more information. + * ``-X showalloccount`` to enable the output of the total count of allocated + objects for each type (only works when built with ``COUNT_ALLOCS`` defined); It also allows passing arbitrary values and retrieving them through the :data:`sys._xoptions` dictionary. @@ -408,6 +410,9 @@ Miscellaneous options .. versionadded:: 3.4 The ``-X showrefcount`` and ``-X tracemalloc`` options. + .. versionadded:: 3.6 + The ``-X showalloccount`` option. + Options you shouldn't use ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -554,6 +559,10 @@ conflict. .. versionchanged:: 3.4 The ``encodingname`` part is now optional. + .. versionchanged:: 3.6 + On Windows, the encoding specified by this variable is ignored for interactive + console buffers unless :envvar:`PYTHONLEGACYWINDOWSIOENCODING` is also specified. + Files and pipes redirected through the standard streams are not affected. .. envvar:: PYTHONNOUSERSITE @@ -619,6 +628,81 @@ conflict. .. versionadded:: 3.4 +.. envvar:: PYTHONMALLOC + + Set the Python memory allocators and/or install debug hooks. + + Set the family of memory allocators used by Python: + + * ``malloc``: use the :c:func:`malloc` function of the C library + for all domains (:c:data:`PYMEM_DOMAIN_RAW`, :c:data:`PYMEM_DOMAIN_MEM`, + :c:data:`PYMEM_DOMAIN_OBJ`). + * ``pymalloc``: use the :ref:`pymalloc allocator <pymalloc>` for + :c:data:`PYMEM_DOMAIN_MEM` and :c:data:`PYMEM_DOMAIN_OBJ` domains and use + the :c:func:`malloc` function for the :c:data:`PYMEM_DOMAIN_RAW` domain. + + Install debug hooks: + + * ``debug``: install debug hooks on top of the default memory allocator + * ``malloc_debug``: same as ``malloc`` but also install debug hooks + * ``pymalloc_debug``: same as ``pymalloc`` but also install debug hooks + + When Python is compiled in release mode, the default is ``pymalloc``. When + compiled in debug mode, the default is ``pymalloc_debug`` and the debug hooks + are used automatically. + + If Python is configured without ``pymalloc`` support, ``pymalloc`` and + ``pymalloc_debug`` are not available, the default is ``malloc`` in release + mode and ``malloc_debug`` in debug mode. + + See the :c:func:`PyMem_SetupDebugHooks` function for debug hooks on Python + memory allocators. + + .. versionadded:: 3.6 + + +.. envvar:: PYTHONMALLOCSTATS + + If set to a non-empty string, Python will print statistics of the + :ref:`pymalloc memory allocator <pymalloc>` every time a new pymalloc object + arena is created, and on shutdown. + + This variable is ignored if the :envvar:`PYTHONMALLOC` environment variable + is used to force the :c:func:`malloc` allocator of the C library, or if + Python is configured without ``pymalloc`` support. + + .. versionchanged:: 3.6 + This variable can now also be used on Python compiled in release mode. + It now has no effect if set to an empty string. + + +.. envvar:: PYTHONLEGACYWINDOWSFSENCODING + + If set to a non-empty string, the default filesystem encoding and errors mode + will revert to their pre-3.6 values of 'mbcs' and 'replace', respectively. + Otherwise, the new defaults 'utf-8' and 'surrogatepass' are used. + + This may also be enabled at runtime with + :func:`sys._enablelegacywindowsfsencoding()`. + + Availability: Windows + + .. versionadded:: 3.6 + See :pep:`529` for more details. + +.. envvar:: PYTHONLEGACYWINDOWSIOENCODING + + If set to a non-empty string, does not use the new console reader and + writer. This means that Unicode characters will be encoded according to + the active console code page, rather than using utf-8. + + This variable is ignored if the standard streams are redirected (to files + or pipes) rather than referring to console buffers. + + Availability: Windows + + .. versionadded:: 3.6 + Debug-mode variables ~~~~~~~~~~~~~~~~~~~~ @@ -634,9 +718,3 @@ if Python was configured with the ``--with-pydebug`` build option. If set, Python will dump objects and reference counts still alive after shutting down the interpreter. - - -.. envvar:: PYTHONMALLOCSTATS - - If set, Python will print memory allocation statistics every time a new - object arena is created, and on shutdown. diff --git a/Doc/using/index.rst b/Doc/using/index.rst index 502afa9033..a5df713944 100644 --- a/Doc/using/index.rst +++ b/Doc/using/index.rst @@ -17,4 +17,3 @@ interpreter and things that make working with Python easier. unix.rst windows.rst mac.rst - scripts.rst diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 05c91bba59..8f1ac3f3fd 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -25,7 +25,7 @@ there. What you get after installing is a number of things: -* A :file:`MacPython 3.5` folder in your :file:`Applications` folder. In here +* A :file:`MacPython 3.6` folder in your :file:`Applications` folder. In here you find IDLE, the development environment that is a standard part of official Python distributions; PythonLauncher, which handles double-clicking Python scripts from the Finder; and the "Build Applet" tool, which allows you to @@ -93,7 +93,7 @@ aware of: programs that talk to the Aqua window manager (in other words, anything that has a GUI) need to be run in a special way. Use :program:`pythonw` instead of :program:`python` to start such scripts. -With Python 3.5, you can use either :program:`python` or :program:`pythonw`. +With Python 3.6, you can use either :program:`python` or :program:`pythonw`. Configuration @@ -159,7 +159,7 @@ https://riverbankcomputing.com/software/pyqt/intro. Distributing Python Applications on the Mac =========================================== -The "Build Applet" tool that is placed in the MacPython 3.5 folder is fine for +The "Build Applet" tool that is placed in the MacPython 3.6 folder is fine for packaging small Python scripts on your own machine to run as a standard Mac application. This tool, however, is not robust enough to distribute Python applications to other users. diff --git a/Doc/using/scripts.rst b/Doc/using/scripts.rst deleted file mode 100644 index 2c87416f1c..0000000000 --- a/Doc/using/scripts.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _tools-and-scripts: - -Additional Tools and Scripts -============================ - -.. _scripts-pyvenv: - -pyvenv - Creating virtual environments --------------------------------------- - -.. include:: venv-create.inc - diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 7ad3008826..53f431b5cf 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -1,31 +1,39 @@ Creation of :ref:`virtual environments <venv-def>` is done by executing the -``pyvenv`` script:: +command ``venv``:: - pyvenv /path/to/new/virtual/environment + python3 -m venv /path/to/new/virtual/environment Running this command creates the target directory (creating any parent directories that don't exist already) and places a ``pyvenv.cfg`` file in it -with a ``home`` key pointing to the Python installation the command was run -from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory +with a ``home`` key pointing to the Python installation from which the command +was run. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy of the ``python`` binary (or binaries, in the case of Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is ``Lib\site-packages``). +.. deprecated:: 3.6 + ``pyvenv`` was the recommended tool for creating virtual environments for + Python 3.3 and 3.4, and is `deprecated in Python 3.6 + <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_. + +.. versionchanged:: 3.5 + The use of ``venv`` is now recommended for creating virtual environments. + .. seealso:: `Python Packaging User Guide: Creating and using virtual environments - <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`__ + <https://packaging.python.org/installing/#creating-virtual-environments>`__ .. highlight:: none -On Windows, you may have to invoke the ``pyvenv`` script as follows, if you -don't have the relevant PATH and PATHEXT settings:: +On Windows, invoke the ``venv`` command as follows:: - c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv + c:\>c:\Python35\python -m venv c:\path\to\myenv -or equivalently:: +Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for +your :ref:`Python installation <using-on-windows>`:: - c:\Temp>c:\Python35\python -m venv myenv + c:\>python -m venv myenv c:\path\to\myenv The command, if run with ``-h``, will show the available options:: @@ -36,25 +44,26 @@ The command, if run with ``-h``, will show the available options:: Creates virtual Python environments in one or more target directories. positional arguments: - ENV_DIR A directory to create the environment in. + ENV_DIR A directory to create the environment in. optional arguments: - -h, --help show this help message and exit - --system-site-packages Give the virtual environment access to the system - site-packages dir. - --symlinks Try to use symlinks rather than copies, when symlinks - are not the default for the platform. - --copies Try to use copies rather than symlinks, even when - symlinks are the default for the platform. - --clear Delete the contents of the environment directory if it - already exists, before environment creation. - --upgrade Upgrade the environment directory to use this version - of Python, assuming Python has been upgraded in-place. - --without-pip Skips installing or upgrading pip in the virtual - environment (pip is bootstrapped by default) - -Depending on how the ``venv`` functionality has been invoked, the usage message -may vary slightly, e.g. referencing ``pyvenv`` rather than ``venv``. + -h, --help show this help message and exit + --system-site-packages + Give the virtual environment access to the system + site-packages dir. + --symlinks Try to use symlinks rather than copies, when symlinks + are not the default for the platform. + --copies Try to use copies rather than symlinks, even when + symlinks are the default for the platform. + --clear Delete the contents of the environment directory if it + already exists, before environment creation. + --upgrade Upgrade the environment directory to use this version + of Python, assuming Python has been upgraded in-place. + --without-pip Skips installing or upgrading pip in the virtual + environment (pip is bootstrapped by default) + + Once an environment has been created, you may wish to activate it, e.g. by + sourcing an activate script in its bin directory. .. versionchanged:: 3.4 Installs pip by default, added the ``--without-pip`` and ``--copies`` @@ -73,12 +82,13 @@ run with the ``--system-site-packages`` option, ``false`` otherwise. Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be invoked to bootstrap ``pip`` into the virtual environment. -Multiple paths can be given to ``pyvenv``, in which case an identical -virtualenv will be created, according to the given options, at each -provided path. +Multiple paths can be given to ``venv``, in which case an identical virtual +environment will be created, according to the given options, at each provided +path. -Once a venv has been created, it can be "activated" using a script in the -venv's binary directory. The invocation of the script is platform-specific: +Once a virtual environment has been created, it can be "activated" using a +script in the virtual environment's binary directory. The invocation of the +script is platform-specific: +-------------+-----------------+-----------------------------------------+ | Platform | Shell | Command to activate virtual environment | @@ -95,16 +105,17 @@ venv's binary directory. The invocation of the script is platform-specific: +-------------+-----------------+-----------------------------------------+ You don't specifically *need* to activate an environment; activation just -prepends the venv's binary directory to your path, so that "python" invokes the -venv's Python interpreter and you can run installed scripts without having to -use their full path. However, all scripts installed in a venv should be -runnable without activating it, and run with the venv's Python automatically. - -You can deactivate a venv by typing "deactivate" in your shell. The exact -mechanism is platform-specific: for example, the Bash activation script defines -a "deactivate" function, whereas on Windows there are separate scripts called -``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is -created. +prepends the virtual environment's binary directory to your path, so that +"python" invokes the virtual environment's Python interpreter and you can run +installed scripts without having to use their full path. However, all scripts +installed in a virtual environment should be runnable without activating it, +and run with the virtual environment's Python automatically. + +You can deactivate a virtual environment by typing "deactivate" in your shell. +The exact mechanism is platform-specific: for example, the Bash activation +script defines a "deactivate" function, whereas on Windows there are separate +scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed +when the virtual environment is created. .. versionadded:: 3.4 ``fish`` and ``csh`` activation scripts. diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index a4a6a30c36..12bdd9d646 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -29,15 +29,15 @@ Supported Versions As specified in :pep:`11`, a Python release only supports a Windows platform while Microsoft considers the platform under extended support. This means that -Python 3.5 supports Windows Vista and newer. If you require Windows XP support -then please install Python 3.4. +Python |version| supports Windows Vista and newer. If you require Windows XP +support then please install Python 3.4. Installation Steps ------------------ -Four Python 3.5 installers are available for download - two each for the 32-bit -and 64-bit versions of the interpreter. The *web installer* is a small initial -download, and it will automatically download the required components as +Four Python |version| installers are available for download - two each for the +32-bit and 64-bit versions of the interpreter. The *web installer* is a small +initial download, and it will automatically download the required components as necessary. The *offline installer* includes the components necessary for a default installation and only requires an internet connection for optional features. See :ref:`install-layout-option` for other ways to avoid downloading @@ -74,6 +74,31 @@ installation". In this case: * If selected, the install directory will be added to the system :envvar:`PATH` * Shortcuts are available for all users +.. _max-path: + +Removing the MAX_PATH Limitation +-------------------------------- + +Windows historically has limited path lengths to 260 characters. This meant that +paths longer than this would not resolve and errors would result. + +In the latest versions of Windows, this limitation can be expanded to +approximately 32,000 characters. Your administrator will need to activate the +"Enable Win32 long paths" group policy, or set the registry value +``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem@LongPathsEnabled`` +to ``1``. + +This allows the :func:`open` function, the :mod:`os` module and most other +path functionality to accept and return paths longer than 260 characters when +using strings. (Use of bytes as paths is deprecated on Windows, and this feature +is not available when using bytes.) + +After changing the above option, no further configuration is required. + +.. versionchanged:: 3.6 + + Support for long paths was enabled in Python. + .. _install-quiet-option: Installing Without UI @@ -168,13 +193,13 @@ of available options is shown below. For example, to silently install a default, system-wide Python installation, you could use the following command (from an elevated command prompt):: - python-3.5.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0 + python-3.6.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0 To allow users to easily install a personal copy of Python without the test suite, you could provide a shortcut with the following command. This will display a simplified initial page and disallow customization:: - python-3.5.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0 + python-3.6.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0 SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite." (Note that omitting the launcher also omits file associations, and is only @@ -209,13 +234,13 @@ where a large number of installations are going to be performed it is very useful to have a locally cached copy. Execute the following command from Command Prompt to download all possible -required files. Remember to substitute ``python-3.5.0.exe`` for the actual +required files. Remember to substitute ``python-3.6.0.exe`` for the actual name of your installer, and to create layouts in their own directories to avoid collisions between files with the same name. :: - python-3.5.0.exe /layout [optional target directory] + python-3.6.0.exe /layout [optional target directory] You may also specify the ``/quiet`` option to hide the progress display. @@ -320,7 +345,7 @@ User level and the System level, or temporarily in a command prompt. To temporarily set environment variables, open Command Prompt and use the :command:`set` command:: - C:\>set PATH=C:\Program Files\Python 3.5;%PATH% + C:\>set PATH=C:\Program Files\Python 3.6;%PATH% C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib C:\>python @@ -376,10 +401,10 @@ Finding the Python executable Besides using the automatically created start menu entry for the Python interpreter, you might want to start Python in the command prompt. The -installer for Python 3.5 and later has an option to set that up for you. +installer has an option to set that up for you. -On the first page of the installer, an option labelled "Add Python 3.5 to -PATH" can be selected to have the installer add the install location into the +On the first page of the installer, an option labelled "Add Python to PATH" +may be selected to have the installer add the install location into the :envvar:`PATH`. The location of the :file:`Scripts\\` folder is also added. This allows you to type :command:`python` to run the interpreter, and :command:`pip` for the package installer. Thus, you can also execute your @@ -393,7 +418,7 @@ of your Python installation, delimited by a semicolon from other entries. An example variable could look like this (assuming the first two entries already existed):: - C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.5 + C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.6 .. _launcher: @@ -418,6 +443,8 @@ Getting started From the command-line ^^^^^^^^^^^^^^^^^^^^^ +.. versionchanged:: 3.6 + System-wide installations of Python 3.3 and later will put the launcher on your :envvar:`PATH`. The launcher is compatible with all available versions of Python, so it does not matter which version is installed. To check that the @@ -427,25 +454,26 @@ launcher is available, execute the following command in Command Prompt: py -You should find that the latest version of Python 2.x you have installed is +You should find that the latest version of Python you have installed is started - it can be exited as normal, and any additional command-line arguments specified will be sent directly to Python. -If you have multiple versions of Python 2.x installed (e.g., 2.6 and 2.7) you -will have noticed that Python 2.7 was started - to launch Python 2.6, try the -command: +If you have multiple versions of Python installed (e.g., 2.7 and |version|) you +will have noticed that Python |version| was started - to launch Python 2.7, try +the command: :: - py -2.6 + py -2.7 -If you have a Python 3.x installed, try the command: +If you want the latest version of Python 2.x you have installed, try the +command: :: - py -3 + py -2 -You should find the latest version of Python 3.x starts. +You should find the latest version of Python 2.x starts. If you see the following error, you do not have the launcher installed: @@ -500,6 +528,11 @@ version qualifier. Assuming you have Python 2.6 installed, try changing the first line to ``#! python2.6`` and you should find the 2.6 version information printed. +Note that unlike interactive use, a bare "python" will use the latest +version of Python 2.x that you have installed. This is for backward +compatibility and for compatibility with Unix, where the command ``python`` +typically refers to Python 2. + From file associations ^^^^^^^^^^^^^^^^^^^^^^ @@ -676,7 +709,7 @@ target Python. -.. finding_modules: +.. _finding_modules: Finding modules =============== @@ -687,7 +720,24 @@ installation directory. So, if you had installed Python to :file:`C:\\Python\\Lib\\` and third-party modules should be stored in :file:`C:\\Python\\Lib\\site-packages\\`. -This is how :data:`sys.path` is populated on Windows: +To completely override :data:`sys.path`, create a ``._pth`` file with the same +name as the DLL (``python36._pth``) or the executable (``python._pth``) and +specify one line for each path to add to :data:`sys.path`. The file based on the +DLL name overrides the one based on the executable, which allows paths to be +restricted for any program loading the runtime if desired. + +When the file exists, all registry and environment variables are ignored, +isolated mode is enabled, and :mod:`site` is not imported unless one line in the +file specifies ``import site``. Blank paths and lines starting with ``#`` are +ignored. Each path may be absolute or relative to the location of the file. +Import statements other than to ``site`` are not permitted, and arbitrary code +cannot be specified. + +Note that ``.pth`` files (without leading underscore) will be processed normally +by the :mod:`site` module. + +When no ``._pth`` file is found, this is how :data:`sys.path` is populated on +Windows: * An empty entry is added at the start, which corresponds to the current directory. @@ -706,10 +756,11 @@ This is how :data:`sys.path` is populated on Windows: * If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as "Python Home". Otherwise, the path of the main Python executable is used to - locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a - Python home is found, the relevant sub-directories added to :data:`sys.path` - (``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core - Python path is constructed from the PythonPath stored in the registry. + locate a "landmark file" (either ``Lib\os.py`` or ``pythonXY.zip``) to deduce + the "Python Home". If a Python home is found, the relevant sub-directories + added to :data:`sys.path` (``Lib``, ``plat-win``, etc) are based on that + folder. Otherwise, the core Python path is constructed from the PythonPath + stored in the registry. * If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in the environment, and no registry entries can be found, a default path with @@ -722,10 +773,6 @@ directory one level above the executable, the following variations apply: path is used instead of the path to the main executable when deducing the home location. -* If ``applocal`` is set to true, the ``home`` property or the main executable - is always used as the home path, and all environment variables or registry - values affecting the path are ignored. The landmark file is not checked. - The end result of all this is: * When running :file:`python.exe`, or any other .exe in the main Python @@ -744,13 +791,12 @@ The end result of all this is: For those who want to bundle Python into their application or distribution, the 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. +* Include a ``._pth`` file alongside your executable containing the + directories to include. This will ignore paths listed in the registry and + environment variables, and also ignore :mod:`site` unless ``import site`` is + listed. -* If you are loading :file:`python3.dll` or :file:`python35.dll` in your own +* If you are loading :file:`python3.dll` or :file:`python36.dll` in your own executable, explicitly call :c:func:`Py_SetPath` or (at least) :c:func:`Py_SetProgramName` before :c:func:`Py_Initialize`. @@ -760,7 +806,8 @@ following advice will prevent conflicts with other installations: * If you cannot use the previous suggestions (for example, you are a distribution that allows people to run :file:`python.exe` directly), ensure that the landmark file (:file:`Lib\\os.py`) exists in your install directory. - (Note that it will not be detected inside a ZIP file.) + (Note that it will not be detected inside a ZIP file, but a correctly named + ZIP file will be detected instead.) 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. @@ -768,6 +815,14 @@ 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. +.. versionchanged:: + 3.6 + + * Adds ``sys.path`` file support and removes ``applocal`` option from + ``pyvenv.cfg``. + * Adds ``pythonXX.zip`` as a potential landmark when directly adjacent + to the executable. + Additional modules ================== @@ -867,7 +922,7 @@ 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``, +optimized ``.pyc`` files in a ZIP, and ``python3.dll``, ``python36.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. |