From 27cc059d49b805bada01b50c8622e408dfbe7902 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Tue, 12 Dec 2023 00:27:35 +0200 Subject: [PATCH 01/11] Fix Sphinx warnings in library/random.rst --- Doc/library/random.rst | 10 +++++----- Doc/tools/.nitignore | 1 - 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 76ae97a8be7e63..48fcda571d0251 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -34,9 +34,9 @@ instance of the :class:`random.Random` class. You can instantiate your own instances of :class:`Random` to get generators that don't share state. Class :class:`Random` can also be subclassed if you want to use a different -basic generator of your own devising: in that case, override the :meth:`~Random.random`, -:meth:`~Random.seed`, :meth:`~Random.getstate`, and :meth:`~Random.setstate` methods. -Optionally, a new generator can supply a :meth:`~Random.getrandbits` method --- this +basic generator of your own devising: in that case, override the :meth:`~random.random`, +:meth:`~random.seed`, :meth:`~random.getstate`, and :meth:`~random.setstate` methods. +Optionally, a new generator can supply a :meth:`~random.getrandbits` method --- this allows :meth:`randrange` to produce selections over an arbitrarily large range. The :mod:`random` module also provides the :class:`SystemRandom` class which @@ -409,7 +409,7 @@ Alternative Generator .. deprecated-removed:: 3.9 3.11 Formerly the *seed* could be any hashable object. Now it is limited to: - :class:`NoneType`, :class:`int`, :class:`float`, :class:`str`, + *NoneType*, :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :class:`bytearray`. .. class:: SystemRandom([seed]) @@ -435,7 +435,7 @@ change across Python versions, but two aspects are guaranteed not to change: * If a new seeding method is added, then a backward compatible seeder will be offered. -* The generator's :meth:`~Random.random` method will continue to produce the same +* The generator's :meth:`~random.random` method will continue to produce the same sequence when the compatible seeder is given the same seed. .. _random-examples: diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 511648ab6991c6..e075e4f527522e 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -79,7 +79,6 @@ Doc/library/profile.rst Doc/library/pyclbr.rst Doc/library/pydoc.rst Doc/library/pyexpat.rst -Doc/library/random.rst Doc/library/readline.rst Doc/library/resource.rst Doc/library/rlcompleter.rst From d3d310fa6938e99c98dd900f7310f1b202519d73 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Tue, 12 Dec 2023 00:27:51 +0200 Subject: [PATCH 02/11] Update links --- Doc/library/random.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 48fcda571d0251..1ebbe2a0b84958 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -572,14 +572,14 @@ Simulation of arrival times and service deliveries for a multiserver queue:: including simulation, sampling, shuffling, and cross-validation. `Economics Simulation - `_ + `_ a simulation of a marketplace by `Peter Norvig `_ that shows effective use of many of the tools and distributions provided by this module (gauss, uniform, sample, betavariate, choice, triangular, and randrange). `A Concrete Introduction to Probability (using Python) - `_ + `_ a tutorial by `Peter Norvig `_ covering the basics of probability theory, how to write simulations, and how to perform data analysis using Python. From bceba6e79156969772258a66a80946c61712f913 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Tue, 12 Dec 2023 19:17:47 +0200 Subject: [PATCH 03/11] NoneType -> None --- Doc/library/random.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 1ebbe2a0b84958..133070a48402f8 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -88,7 +88,7 @@ Bookkeeping functions .. versionchanged:: 3.11 The *seed* must be one of the following types: - *NoneType*, :class:`int`, :class:`float`, :class:`str`, + ``None``, :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :class:`bytearray`. .. function:: getstate() @@ -409,7 +409,7 @@ Alternative Generator .. deprecated-removed:: 3.9 3.11 Formerly the *seed* could be any hashable object. Now it is limited to: - *NoneType*, :class:`int`, :class:`float`, :class:`str`, + ``None``, :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :class:`bytearray`. .. class:: SystemRandom([seed]) From 4bbac89bdb87d2db0b715b93fe2341aae9258e9b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Tue, 12 Dec 2023 21:35:25 +0200 Subject: [PATCH 04/11] Fix references to undocumented class methods --- Doc/library/random.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 133070a48402f8..f7cd09b460a6d0 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -34,9 +34,9 @@ instance of the :class:`random.Random` class. You can instantiate your own instances of :class:`Random` to get generators that don't share state. Class :class:`Random` can also be subclassed if you want to use a different -basic generator of your own devising: in that case, override the :meth:`~random.random`, -:meth:`~random.seed`, :meth:`~random.getstate`, and :meth:`~random.setstate` methods. -Optionally, a new generator can supply a :meth:`~random.getrandbits` method --- this +basic generator of your own devising: in that case, override the :meth:`!random`, +:meth:`!seed`, :meth:`!getstate`, and :meth:`!setstate` methods. +Optionally, a new generator can supply a :meth:`!getrandbits` method --- this allows :meth:`randrange` to produce selections over an arbitrarily large range. The :mod:`random` module also provides the :class:`SystemRandom` class which From 01af3f1aa31786a804792f23696664255535309d Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 13 Dec 2023 21:34:01 +0200 Subject: [PATCH 05/11] Fix references to undocumented class methods --- Doc/library/random.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index f7cd09b460a6d0..cf1566d0f60c25 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -435,7 +435,7 @@ change across Python versions, but two aspects are guaranteed not to change: * If a new seeding method is added, then a backward compatible seeder will be offered. -* The generator's :meth:`~random.random` method will continue to produce the same +* The generator's :meth:`!random` method will continue to produce the same sequence when the compatible seeder is given the same seed. .. _random-examples: From 9093f5c3540c0e6095182dab9ba3fa48e71405fa Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 25 Dec 2023 15:44:29 +0200 Subject: [PATCH 06/11] Add stub entries for Random methods --- Doc/library/random.rst | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 0e006afd67a939..d66355c60e8607 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -34,9 +34,9 @@ instance of the :class:`random.Random` class. You can instantiate your own instances of :class:`Random` to get generators that don't share state. Class :class:`Random` can also be subclassed if you want to use a different -basic generator of your own devising: in that case, override the :meth:`!random`, -:meth:`!seed`, :meth:`!getstate`, and :meth:`!setstate` methods. -Optionally, a new generator can supply a :meth:`!getrandbits` method --- this +basic generator of your own devising: in that case, override the :meth:`~Random.random`, +:meth:`~Random.seed`, :meth:`~Random.getstate`, and :meth:`~Random.setstate` methods. +Optionally, a new generator can supply a :meth:`~Random.getrandbits` method --- this allows :meth:`randrange` to produce selections over an arbitrarily large range. The :mod:`random` module also provides the :class:`SystemRandom` class which @@ -412,6 +412,31 @@ Alternative Generator ``None``, :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :class:`bytearray`. + .. method:: Random.seed() + + Override this method in subclasses to customise the :meth:`random.seed` + behaviour of :class:`Random` instances. + + .. method:: Random.getstate() + + Override this method in subclasses to customise the :meth:`random.getstate` + behaviour of :class:`Random` instances. + + .. method:: Random.setstate() + + Override this method in subclasses to customise the :meth:`random.setstate` + behaviour of :class:`Random` instances. + + .. method:: Random.getrandbits() + + Override this method in subclasses to customise the :meth:`random.getrandbits` + behaviour of :class:`Random` instances. + + .. method:: Random.random() + + Override this method in subclasses to customise the :meth:`random.random` + behaviour of :class:`Random` instances. + .. class:: SystemRandom([seed]) Class that uses the :func:`os.urandom` function for generating random numbers @@ -435,7 +460,7 @@ change across Python versions, but two aspects are guaranteed not to change: * If a new seeding method is added, then a backward compatible seeder will be offered. -* The generator's :meth:`!random` method will continue to produce the same +* The generator's :meth:`~Random.random` method will continue to produce the same sequence when the compatible seeder is given the same seed. .. _random-examples: From 038f7152699c31aff4708ac2c987e93008f52ec0 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 25 Dec 2023 16:05:53 +0200 Subject: [PATCH 07/11] Move comments inwards to fit without horizontal scrolling --- Doc/library/random.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index d66355c60e8607..f15da9cf5d5483 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -470,30 +470,30 @@ Examples Basic examples:: - >>> random() # Random float: 0.0 <= x < 1.0 + >>> random() # Random float: 0.0 <= x < 1.0 0.37444887175646646 - >>> uniform(2.5, 10.0) # Random float: 2.5 <= x <= 10.0 + >>> uniform(2.5, 10.0) # Random float: 2.5 <= x <= 10.0 3.1800146073117523 - >>> expovariate(1 / 5) # Interval between arrivals averaging 5 seconds + >>> expovariate(1 / 5) # Interval between arrivals averaging 5 seconds 5.148957571865031 - >>> randrange(10) # Integer from 0 to 9 inclusive + >>> randrange(10) # Integer from 0 to 9 inclusive 7 - >>> randrange(0, 101, 2) # Even integer from 0 to 100 inclusive + >>> randrange(0, 101, 2) # Even integer from 0 to 100 inclusive 26 - >>> choice(['win', 'lose', 'draw']) # Single random element from a sequence + >>> choice(['win', 'lose', 'draw']) # Single random element from a sequence 'draw' >>> deck = 'ace two three four'.split() - >>> shuffle(deck) # Shuffle a list + >>> shuffle(deck) # Shuffle a list >>> deck ['four', 'two', 'ace', 'three'] - >>> sample([10, 20, 30, 40, 50], k=4) # Four samples without replacement + >>> sample([10, 20, 30, 40, 50], k=4) # Four samples without replacement [40, 10, 50, 30] Simulations:: From bc536ba1c3da8bc5b39a99373ed78bda360257d5 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Thu, 28 Dec 2023 19:03:02 +0200 Subject: [PATCH 08/11] Move info about subclassing to one place; update signatures --- Doc/library/random.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index f15da9cf5d5483..a12089ee6be24f 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -34,10 +34,8 @@ instance of the :class:`random.Random` class. You can instantiate your own instances of :class:`Random` to get generators that don't share state. Class :class:`Random` can also be subclassed if you want to use a different -basic generator of your own devising: in that case, override the :meth:`~Random.random`, -:meth:`~Random.seed`, :meth:`~Random.getstate`, and :meth:`~Random.setstate` methods. -Optionally, a new generator can supply a :meth:`~Random.getrandbits` method --- this -allows :meth:`randrange` to produce selections over an arbitrarily large range. +basic generator of your own devising: see the documentation on that class for +more details. The :mod:`random` module also provides the :class:`SystemRandom` class which uses the system function :func:`os.urandom` to generate random numbers @@ -412,7 +410,10 @@ Alternative Generator ``None``, :class:`int`, :class:`float`, :class:`str`, :class:`bytes`, or :class:`bytearray`. - .. method:: Random.seed() + Subclasses of :class:`!Random` should override the following methods if they + wish to make use of a different basic generator: + + .. method:: Random.seed(a=None, version=2) Override this method in subclasses to customise the :meth:`random.seed` behaviour of :class:`Random` instances. @@ -422,21 +423,26 @@ Alternative Generator Override this method in subclasses to customise the :meth:`random.getstate` behaviour of :class:`Random` instances. - .. method:: Random.setstate() + .. method:: Random.setstate(state) Override this method in subclasses to customise the :meth:`random.setstate` behaviour of :class:`Random` instances. - .. method:: Random.getrandbits() - - Override this method in subclasses to customise the :meth:`random.getrandbits` - behaviour of :class:`Random` instances. - .. method:: Random.random() Override this method in subclasses to customise the :meth:`random.random` behaviour of :class:`Random` instances. + Optionally, a new generator can also supply the following method: + + .. method:: Random.getrandbits(k) + + Override this method in subclasses to customise the + :meth:`random.getrandbits` behaviour of :class:`Random` instances. This in + turn allows :meth:`!Random.randrange` to produce selections over an + arbitrarily large range. + + .. class:: SystemRandom([seed]) Class that uses the :func:`os.urandom` function for generating random numbers From 534f6b8123bde8e9c413eb0d68c43d70d374d6fc Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Thu, 28 Dec 2023 10:23:12 -0700 Subject: [PATCH 09/11] Squigglify for readability Co-authored-by: Alex Waygood --- Doc/library/random.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index a12089ee6be24f..00c277508455f5 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -415,22 +415,22 @@ Alternative Generator .. method:: Random.seed(a=None, version=2) - Override this method in subclasses to customise the :meth:`random.seed` + Override this method in subclasses to customise the :meth:`~random.seed` behaviour of :class:`Random` instances. .. method:: Random.getstate() - Override this method in subclasses to customise the :meth:`random.getstate` + Override this method in subclasses to customise the :meth:`~random.getstate` behaviour of :class:`Random` instances. .. method:: Random.setstate(state) - Override this method in subclasses to customise the :meth:`random.setstate` + Override this method in subclasses to customise the :meth:`~random.setstate` behaviour of :class:`Random` instances. .. method:: Random.random() - Override this method in subclasses to customise the :meth:`random.random` + Override this method in subclasses to customise the :meth:`~random.random` behaviour of :class:`Random` instances. Optionally, a new generator can also supply the following method: @@ -438,7 +438,7 @@ Alternative Generator .. method:: Random.getrandbits(k) Override this method in subclasses to customise the - :meth:`random.getrandbits` behaviour of :class:`Random` instances. This in + :meth:`~random.getrandbits` behaviour of :class:`Random` instances. This in turn allows :meth:`!Random.randrange` to produce selections over an arbitrarily large range. From 62d7344848ec674d5cd8ac1d9eaf85246ee879ab Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Thu, 28 Dec 2023 17:35:46 +0000 Subject: [PATCH 10/11] suppress links to the class we're already in --- Doc/library/random.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 00c277508455f5..752e2eda0f0168 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -416,29 +416,29 @@ Alternative Generator .. method:: Random.seed(a=None, version=2) Override this method in subclasses to customise the :meth:`~random.seed` - behaviour of :class:`Random` instances. + behaviour of :class:`!Random` instances. .. method:: Random.getstate() Override this method in subclasses to customise the :meth:`~random.getstate` - behaviour of :class:`Random` instances. + behaviour of :class:`!Random` instances. .. method:: Random.setstate(state) Override this method in subclasses to customise the :meth:`~random.setstate` - behaviour of :class:`Random` instances. + behaviour of :class:`!Random` instances. .. method:: Random.random() Override this method in subclasses to customise the :meth:`~random.random` - behaviour of :class:`Random` instances. + behaviour of :class:`!Random` instances. Optionally, a new generator can also supply the following method: .. method:: Random.getrandbits(k) Override this method in subclasses to customise the - :meth:`~random.getrandbits` behaviour of :class:`Random` instances. This in + :meth:`~random.getrandbits` behaviour of :class:`!Random` instances. This in turn allows :meth:`!Random.randrange` to produce selections over an arbitrarily large range. From 2ba1663d6bf540ed8a8e52557a04cc5b3a877614 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Thu, 28 Dec 2023 12:05:54 -0700 Subject: [PATCH 11/11] Update Random.getrandbits Co-authored-by: Alex Waygood --- Doc/library/random.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 752e2eda0f0168..d0ced2416c9578 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -433,14 +433,12 @@ Alternative Generator Override this method in subclasses to customise the :meth:`~random.random` behaviour of :class:`!Random` instances. - Optionally, a new generator can also supply the following method: + Optionally, a custom generator subclass can also supply the following method: .. method:: Random.getrandbits(k) Override this method in subclasses to customise the - :meth:`~random.getrandbits` behaviour of :class:`!Random` instances. This in - turn allows :meth:`!Random.randrange` to produce selections over an - arbitrarily large range. + :meth:`~random.getrandbits` behaviour of :class:`!Random` instances. .. class:: SystemRandom([seed])