diff options
Diffstat (limited to 'Doc/using/cmdline.rst')
| -rw-r--r-- | Doc/using/cmdline.rst | 58 |
1 files changed, 33 insertions, 25 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index cd4d02f..2703684 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 [-bBdEhiORqsSuvVWx?] [-c command | -m module-name | script | - ] [args] + python [-bBdEhiOqsSuvVWx?] [-c command | -m module-name | script | - ] [args] The most common use case is, of course, a simple invocation of a script:: @@ -229,23 +229,22 @@ Miscellaneous options .. cmdoption:: -R - Turn on hash randomization, so that the :meth:`__hash__` values of str, bytes - and datetime objects are "salted" with an unpredictable random value. - Although they remain constant within an individual Python process, they are - not predictable between repeated invocations of Python. + Kept for compatibility. On Python 3.3 and greater, hash randomization is + turned on by default. - This is intended to provide protection against a denial-of-service caused by - carefully-chosen inputs that exploit the worst case performance of a dict - construction, O(n^2) complexity. See - http://www.ocert.org/advisories/ocert-2011-003.html for details. + On previous versions of Python, this option turns on hash randomization, + so that the :meth:`__hash__` values of str, bytes and datetime + are "salted" with an unpredictable random value. Although they remain + constant within an individual Python process, they are not predictable + between repeated invocations of Python. - Changing hash values affects the order in which keys are retrieved from a - dict. Although Python has never made guarantees about this ordering (and it - typically varies between 32-bit and 64-bit builds), enough real-world code - implicitly relies on this non-guaranteed behavior that the randomization is - disabled by default. + Hash randomization is intended to provide protection against a + denial-of-service caused by carefully-chosen inputs that exploit the worst + case performance of a dict construction, O(n^2) complexity. See + http://www.ocert.org/advisories/ocert-2011-003.html for details. - See also :envvar:`PYTHONHASHSEED`. + :envvar:`PYTHONHASHSEED` allows you to set a fixed value for the hash + seed secret. .. versionadded:: 3.2.3 @@ -263,7 +262,9 @@ Miscellaneous options .. cmdoption:: -S Disable the import of the module :mod:`site` and the site-dependent - manipulations of :data:`sys.path` that it entails. + manipulations of :data:`sys.path` that it entails. Also disable these + manipulations if :mod:`site` is explicitly imported later (call + :func:`site.main` if you want them to be triggered). .. cmdoption:: -u @@ -357,7 +358,8 @@ Miscellaneous options .. cmdoption:: -X Reserved for various implementation-specific options. CPython currently - defines none of them, but allows to pass arbitrary values and retrieve + defines just one, you can use ``-X faulthander`` to enable + :data:`faulthandler`. It also allows to pass arbitrary values and retrieve them through the :data:`sys._xoptions` dictionary. .. versionchanged:: 3.2 @@ -475,7 +477,7 @@ conflict. .. envvar:: PYTHONCASEOK If this is set, Python ignores case in :keyword:`import` statements. This - only works on Windows, OS X, and OS/2. + only works on Windows and OS X. .. envvar:: PYTHONDONTWRITEBYTECODE @@ -487,9 +489,8 @@ conflict. .. envvar:: PYTHONHASHSEED - If this variable is set to ``random``, the effect is the same as specifying - the :option:`-R` option: a random value is used to seed the hashes of str, - bytes and datetime objects. + If this variable is not set or set to ``random``, a random value is used + to seed the hashes of str, bytes and datetime objects. If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a fixed seed for generating the hash() of the types covered by the hash @@ -500,8 +501,7 @@ conflict. values. The integer must be a decimal number in the range [0,4294967295]. Specifying - the value 0 will lead to the same hash values as when hash randomization is - disabled. + the value 0 will disable hash randomization. .. versionadded:: 3.2.3 @@ -531,8 +531,8 @@ conflict. Defines the :data:`user base directory <site.USER_BASE>`, which is used to compute the path of the :data:`user site-packages directory <site.USER_SITE>` - and :ref:`Distutils installation paths <inst-alt-install-user>` for ``python - setup.py install --user``. + and :ref:`Distutils installation paths <inst-alt-install-user>` for + ``python setup.py install --user``. .. seealso:: @@ -551,6 +551,14 @@ conflict. separated string, it is equivalent to specifying :option:`-W` multiple times. +.. 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. + Debug-mode variables ~~~~~~~~~~~~~~~~~~~~ |