Skip to content

bpo-40541: Add optional *counts* parameter to random.sample() #19970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhettinger merged 10 commits into from
May 8, 2020
Merged

bpo-40541: Add optional *counts* parameter to random.sample() #19970

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4ad778b
Add weights to random.sample()
rhettinger May 6, 2020
eaed7b3
Add docs
rhettinger May 6, 2020
787ec38
Add blurb
rhettinger May 6, 2020
ab6b380
Add tests
rhettinger May 6, 2020
ea5e42e
Update Doc/library/random.rst
rhettinger May 6, 2020
672f739
Add exact equidistribution test
rhettinger May 7, 2020
556582d
Earlier test for zero total weight
rhettinger May 7, 2020
4fb554a
Change parameter name from "weights" to "counts". Add another test.
rhettinger May 7, 2020
55e948e
Sync-up docstring with the main docs
rhettinger May 7, 2020
1f36ad3
Fix typo and improve formatting
rhettinger May 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Add docs
  • Loading branch information
@rhettinger
rhettinger committed May 6, 2020
commit eaed7b3bab73a37f98eb750ef6f1091cd537c7b3
20 changes: 13 additions & 7 deletions Doc/library/random.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ Functions for sequences
The optional parameter *random*.


.. function:: sample(population, k)
.. function:: sample(population, k, *, weights=None)

Return a *k* length list of unique elements chosen from the population sequence
or set. Used for random sampling without replacement.
Expand All @@ -231,13 +231,20 @@ Functions for sequences
Members of the population need not be :term:`hashable` or unique. If the population
contains repeats, then each occurrence is a possible selection in the sample.

If *weights* are given, they must be non-negative integer counts.
Each selection effectively reduces the count by one, lowering
the probablity for the next selection.

To choose a sample from a range of integers, use a :func:`range` object as an
argument. This is especially fast and space efficient for sampling from a large
population: ``sample(range(10000000), k=60)``.

If the sample size is larger than the population size, a :exc:`ValueError`
is raised.

.. versionchanged 3.9
Comment thread
rhettinger marked this conversation as resolved.
Outdated
Added the *weights* parameter.

.. deprecated:: 3.9
In the future, the *population* must be a sequence. Instances of
:class:`set` are no longer supported. The set must first be converted
Expand Down Expand Up @@ -420,12 +427,11 @@ Simulations::
>>> choices(['red', 'black', 'green'], [18, 18, 2], k=6)
['red', 'green', 'black', 'black', 'red', 'black']

>>> # Deal 20 cards without replacement from a deck of 52 playing cards
>>> # and determine the proportion of cards with a ten-value
>>> # (a ten, jack, queen, or king).
>>> deck = collections.Counter(tens=16, low_cards=36)
>>> seen = sample(list(deck.elements()), k=20)
>>> seen.count('tens') / 20
>>> # Deal 20 cards without replacement from a deck
>>> # of 52 playing cards, and determine the proportion of cards
>>> # with a ten-value: ten, jack, queen, or king.
>>> dealt = sample(['tens', 'low cards'], weights=[16, 36], k=20)
>>> dealt.count('tens') / 20
0.15

>>> # Estimate the probability of getting 5 or more heads from 7 spins
Expand Down