Clarify that hash randomization is on by default

1 files changed, 16 insertions, 17 deletions

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index b14f3704dc..8864b794cb 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -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.
-
-   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
+   Kept for compatibility.  On Python 3.3 and greater, hash randomization is
+   turned on by default.
+
+   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.
+
+   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.
 
-   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.
-
-   See also :envvar:`PYTHONHASHSEED`.
+   :envvar:`PYTHONHASHSEED` allows you to set a fixed value for the hash
+   seed secret.
 
    .. versionadded:: 3.2.3
 
@@ -486,8 +485,8 @@ These environment variables influence Python's behavior.
 
 .. envvar:: PYTHONHASHSEED
 
-   If this variable is set to ``random``, 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