diff options
Diffstat (limited to 'Doc/using')
| -rw-r--r-- | Doc/using/cmdline.rst | 65 | ||||
| -rw-r--r-- | Doc/using/mac.rst | 6 | ||||
| -rw-r--r-- | Doc/using/venv-create.inc | 39 |
3 files changed, 74 insertions, 36 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 4e7168f..e8a329e 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -24,7 +24,7 @@ Command line When invoking Python, you may specify any of these options:: - python [-bBdEhiOqsSuvVWx?] [-c command | -m module-name | script | - ] [args] + python [-bBdEhiIOqsSuvVWx?] [-c command | -m module-name | script | - ] [args] The most common use case is, of course, a simple invocation of a script:: @@ -147,7 +147,12 @@ source. If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is an empty string (``""``) and the current directory will be added to the -start of :data:`sys.path`. +start of :data:`sys.path`. Also, tab-completion and history editing is +automatically enabled, if available on your platform (see +:ref:`rlcompleter-config`). + +.. versionchanged:: 3.4 + Automatic enabling of tab-completion and history editing. .. seealso:: :ref:`tut-invoking` @@ -170,6 +175,8 @@ Generic options Python 3.0 +.. _using-on-misc-options: + Miscellaneous options ~~~~~~~~~~~~~~~~~~~~~ @@ -208,6 +215,17 @@ Miscellaneous options raises an exception. See also :envvar:`PYTHONINSPECT`. +.. cmdoption:: -I + + Run Python in isolated mode. This also implies -E and -s. + In isolated mode :data:`sys.path` contains neither the script's directory nor + the user's site-packages directory. All :envvar:`PYTHON*` environment + variables are ignored, too. Further restrictions may be imposed to prevent + the user from injecting malicious code. + + .. versionadded:: 3.4 + + .. cmdoption:: -O Turn on basic optimizations. This changes the filename extension for @@ -358,9 +376,14 @@ Miscellaneous options .. cmdoption:: -X Reserved for various implementation-specific options. CPython currently - defines just one, you can use ``-X faulthandler`` to enable - :mod:`faulthandler`. It also allows to pass arbitrary values and retrieve - them through the :data:`sys._xoptions` dictionary. + defines two possible values: + + * ``-X faulthandler`` to enable :mod:`faulthandler`; + * ``-X showrefcount`` to enable the output of the total reference count + and memory blocks (only works on debug builds); + + It also allows to pass arbitrary values and retrieve them through the + :data:`sys._xoptions` dictionary. .. versionchanged:: 3.2 It is now allowed to pass :option:`-X` with CPython. @@ -368,6 +391,9 @@ Miscellaneous options .. versionadded:: 3.3 The ``-X faulthandler`` option. + .. versionadded:: 3.4 + The ``-X showrefcount`` option. + Options you shouldn't use ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -385,7 +411,7 @@ Environment variables --------------------- These environment variables influence Python's behavior, they are processed -before the command-line switches other than -E. It is customary that +before the command-line switches other than -E or -I. It is customary that command-line switches override environmental variables where there is a conflict. @@ -430,7 +456,7 @@ conflict. is executed in the same namespace where interactive commands are executed so that objects defined or imported in it can be used without qualification in the interactive session. You can also change the prompts :data:`sys.ps1` and - :data:`sys.ps2` in this file. + :data:`sys.ps2` and the hook :data:`sys.__interactivehook__` in this file. .. envvar:: PYTHONY2K @@ -485,9 +511,9 @@ conflict. .. envvar:: PYTHONDONTWRITEBYTECODE - If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the - import of source modules. This is equivalent to specifying the :option:`-B` - option. + If this is set to a non-empty string, Python won't try to write ``.pyc`` or + ``.pyo`` files on the import of source modules. This is equivalent to + specifying the :option:`-B` option. .. envvar:: PYTHONHASHSEED @@ -512,13 +538,16 @@ conflict. .. envvar:: PYTHONIOENCODING If this is set before running the interpreter, it overrides the encoding used - for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. The - ``:errorhandler`` part is optional and has the same meaning as in - :func:`str.encode`. + for stdin/stdout/stderr, in the syntax ``encodingname:errorhandler``. Both + the ``encodingname`` and the ``:errorhandler`` parts are optional and have + the same meaning as in :func:`str.encode`. For stderr, the ``:errorhandler`` part is ignored; the handler will always be ``'backslashreplace'``. + .. versionchanged:: 3.4 + The ``encodingname`` part is now optional. + .. envvar:: PYTHONNOUSERSITE @@ -556,11 +585,11 @@ conflict. .. envvar:: PYTHONFAULTHANDLER - If this environment variable is set, :func:`faulthandler.enable` is called - at startup: install a handler for :const:`SIGSEGV`, :const:`SIGFPE`, - :const:`SIGABRT`, :const:`SIGBUS` and :const:`SIGILL` signals to dump the - Python traceback. This is equivalent to :option:`-X` ``faulthandler`` - option. + If this environment variable is set to a non-empty string, + :func:`faulthandler.enable` is called at startup: install a handler for + :const:`SIGSEGV`, :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and + :const:`SIGILL` signals to dump the Python traceback. This is equivalent to + :option:`-X` ``faulthandler`` option. .. versionadded:: 3.3 diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index 3e1b74d..5be439f 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.3` folder in your :file:`Applications` folder. In here +* A :file:`MacPython 3.4` 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.3, you can use either :program:`python` or :program:`pythonw`. +With Python 3.4, you can use either :program:`python` or :program:`pythonw`. Configuration @@ -158,7 +158,7 @@ http://www.riverbankcomputing.co.uk/software/pyqt/intro. Distributing Python Applications on the Mac =========================================== -The "Build Applet" tool that is placed in the MacPython 3.3 folder is fine for +The "Build Applet" tool that is placed in the MacPython 3.4 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/venv-create.inc b/Doc/using/venv-create.inc index 5fdbc9b..868bbc8 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -25,7 +25,7 @@ or equivalently:: The command, if run with ``-h``, will show the available options:: usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear] - [--upgrade] ENV_DIR [ENV_DIR ...] + [--upgrade] [--without-pip] ENV_DIR [ENV_DIR ...] Creates virtual Python environments in one or more target directories. @@ -43,6 +43,11 @@ The command, if run with ``-h``, will show the available options:: raised. --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) + +.. versionchanged:: 3.4 + Installs pip by default, added the ``--without-pip`` option If the target directory already exists an error will be raised, unless the ``--clear`` or ``--upgrade`` option was provided. @@ -51,25 +56,29 @@ The created ``pyvenv.cfg`` file also includes the ``include-system-site-packages`` key, set to ``true`` if ``venv`` is 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. 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: on -a Posix platform, you would typically do:: - - $ source <venv>/bin/activate - -whereas on Windows, you might do:: - - C:\> <venv>/Scripts/activate - -if you are using the ``cmd.exe`` shell, or perhaps:: - - PS C:\> <venv>/Scripts/Activate.ps1 - -if you use PowerShell. +venv's binary directory. The invocation of the script is platform-specific: + ++-------------+-----------------+-----------------------------------------+ +| Platform | Shell | Command to activate virtual environment | ++=============+=================+=========================================+ +| Posix | bash/zsh | $ source <venv>/bin/activate | ++-------------+-----------------+-----------------------------------------+ +| | fish | $ . <venv>/bin/activate.fish | ++-------------+-----------------+-----------------------------------------+ +| | csh/tcsh | $ source <venv>/bin/activate.csh | ++-------------+-----------------+-----------------------------------------+ +| Windows | cmd.exe | C:\> <venv>/Scripts/activate.bat | ++-------------+-----------------+-----------------------------------------+ +| | PowerShell | PS C:\> <venv>/Scripts/Activate.ps1 | ++-------------+-----------------+-----------------------------------------+ 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 |