diff options
Diffstat (limited to 'Doc/using')
| -rw-r--r-- | Doc/using/cmdline.rst | 59 | ||||
| -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 | 22 |
6 files changed, 124 insertions, 71 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 57faf89e1a..37a9e14b23 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -619,6 +624,54 @@ 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. + + Debug-mode variables ~~~~~~~~~~~~~~~~~~~~ @@ -634,9 +687,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..3f6b68d133 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -418,6 +418,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 +429,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 +If you have multiple versions of Python installed (e.g., 2.7 and 3.6) you +will have noticed that Python 3.6 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 +503,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 ^^^^^^^^^^^^^^^^^^^^^^ |